abc/GmSSL
1
0
Fork 0
mirror of https://github.com/guanzhi/GmSSL.git synced 2026-06-30 17:53:39 +08:00
Code Issues Packages Projects Releases Wiki Activity

Revert "quantum init"

Browse Source 
This reverts commit 53af3b51ae.
This commit is contained in:
Simon
2018-01-04 14:03:27 +08:00
parent 53af3b51ae
commit 38395c5c80
2361 changed files with 144430 additions and 387427 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
doc/HOWTO/proxy_certificates.txt
View File

@@ -164,138 +164,151 @@ You need the following ingredients:
Here is some skeleton code you can fill in:
/* In this example, I will use a view of granted rights as a bit
array, one bit for each possible right. */
#include <string.h>
#include <netdb.h>
#include <openssl/x509.h>
#include <openssl/x509v3.h>
#define total_rights 25
/*
* In this example, I will use a view of granted rights as a bit
* array, one bit for each possible right.
*/
typedef struct your_rights {
unsigned char rights[total_rights / 8];
unsigned char rights[(total_rights + 7) / 8];
} YOUR_RIGHTS;
/* The following procedure will create an index for the ex_data
store in the X509 validation context the first time it's called.
Subsequent calls will return the same index. */
static int get_proxy_auth_ex_data_idx(void)
/*
* The following procedure will create an index for the ex_data
* store in the X509 validation context the first time it's called.
* Subsequent calls will return the same index. */
static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx)
{
static volatile int idx = -1;
if (idx < 0)
{
CRYPTO_w_lock(CRYPTO_LOCK_X509_STORE);
if (idx < 0)
{
idx = X509_STORE_CTX_get_ex_new_index(0,
"for verify callback",
NULL,NULL,NULL);
static volatile int idx = -1;
if (idx < 0) {
X509_STORE_lock(X509_STORE_CTX_get0_store(ctx));
if (idx < 0) {
idx = X509_STORE_CTX_get_ex_new_index(0,
"for verify callback",
NULL,NULL,NULL);
}
CRYPTO_w_unlock(CRYPTO_LOCK_X509_STORE);
X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx));
}
return idx;
return idx;
}
/* Callback to be given to the X509 validation procedure. */
static int verify_callback(int ok, X509_STORE_CTX *ctx)
{
if (ok == 1) /* It's REALLY important you keep the proxy policy
check within this section. It's important to know
that when ok is 1, the certificates are checked
from top to bottom. You get the CA root first,
followed by the possible chain of intermediate
CAs, followed by the EE certificate, followed by
the possible proxy certificates. */
{
X509 *xs = ctx->current_cert;
if (ok == 1) {
/*
* It's REALLY important you keep the proxy policy
* check within this section. It's important to know
* that when ok is 1, the certificates are checked
* from top to bottom. You get the CA root first,
* followed by the possible chain of intermediate
* CAs, followed by the EE certificate, followed by
* the possible proxy certificates.
*/
X509 *xs = X509_STORE_CTX_get_current_cert(ctx);
if (xs->ex_flags & EXFLAG_PROXY)
{
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx());
PROXY_CERT_INFO_EXTENSION *pci =
X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
if (X509_get_extension_flags(xs) & EXFLAG_PROXY) {
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx(ctx));
PROXY_CERT_INFO_EXTENSION *pci =
X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage))
{
switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) {
case NID_Independent:
/* Do whatever you need to grant explicit rights to
this particular proxy certificate, usually by
pulling them from some database. If there are none
to be found, clear all rights (making this and any
subsequent proxy certificate void of any rights).
*/
memset(rights->rights, 0, sizeof(rights->rights));
break;
/*
* Do whatever you need to grant explicit rights to
* this particular proxy certificate, usually by
* pulling them from some database. If there are none
* to be found, clear all rights (making this and any
* subsequent proxy certificate void of any rights).
*/
memset(rights->rights, 0, sizeof(rights->rights));
break;
case NID_id_ppl_inheritAll:
/* This is basically a NOP, we simply let the current
rights stand as they are. */
break;
/*
* This is basically a NOP, we simply let the current
* rights stand as they are.
*/
break;
default:
/* This is usually the most complex section of code.
You really do whatever you want as long as you
follow RFC 3820. In the example we use here, the
simplest thing to do is to build another, temporary
bit array and fill it with the rights granted by
the current proxy certificate, then use it as a
mask on the accumulated rights bit array, and
voilà, you now have a new accumulated rights bit
array. */
{
int i;
YOUR_RIGHTS tmp_rights;
memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights));
/* This is usually the most complex section of code.
* You really do whatever you want as long as you
* follow RFC 3820. In the example we use here, the
* simplest thing to do is to build another, temporary
* bit array and fill it with the rights granted by
* the current proxy certificate, then use it as a
* mask on the accumulated rights bit array, and
* voilà, you now have a new accumulated rights bit
* array.
*/
{
int i;
YOUR_RIGHTS tmp_rights;
memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights));
/* process_rights() is supposed to be a procedure
that takes a string and it's length, interprets
it and sets the bits in the YOUR_RIGHTS pointed
at by the third argument. */
process_rights((char *) pci->proxyPolicy->policy->data,
pci->proxyPolicy->policy->length,
&tmp_rights);
/*
* process_rights() is supposed to be a procedure
* that takes a string and it's length, interprets
* it and sets the bits in the YOUR_RIGHTS pointed
* at by the third argument.
*/
process_rights((char *) pci->proxyPolicy->policy->data,
pci->proxyPolicy->policy->length,
&tmp_rights);
for(i = 0; i < total_rights / 8; i++)
rights->rights[i] &= tmp_rights.rights[i];
}
break;
for(i = 0; i < total_rights / 8; i++)
rights->rights[i] &= tmp_rights.rights[i];
}
break;
}
PROXY_CERT_INFO_EXTENSION_free(pci);
}
else if (!(xs->ex_flags & EXFLAG_CA))
{
/* We have a EE certificate, let's use it to set default!
*/
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx());
PROXY_CERT_INFO_EXTENSION_free(pci);
} else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) {
/* We have an EE certificate, let's use it to set default! */
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx(ctx));
/* The following procedure finds out what rights the owner
of the current certificate has, and sets them in the
YOUR_RIGHTS structure pointed at by the second
argument. */
set_default_rights(xs, rights);
/* The following procedure finds out what rights the owner
* of the current certificate has, and sets them in the
* YOUR_RIGHTS structure pointed at by the second
* argument.
*/
set_default_rights(xs, rights);
}
}
return ok;
return ok;
}
static int my_X509_verify_cert(X509_STORE_CTX *ctx,
YOUR_RIGHTS *needed_rights)
{
int i;
int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = ctx->verify_cb;
YOUR_RIGHTS rights;
int ok;
int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) =
X509_STORE_CTX_get_verify_cb(ctx);
YOUR_RIGHTS rights;
X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(), &rights);
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
ok = X509_verify_cert(ctx);
X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx), &rights);
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
ok = X509_verify_cert(ctx);
if (ok == 1)
{
ok = check_needed_rights(rights, needed_rights);
if (ok == 1) {
ok = check_needed_rights(rights, needed_rights);
}
X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
return ok;
return ok;
}
If you use SSL or TLS, you can easily set up a callback to have the
certificates checked properly, using the code above:

3
doc/README
View File

@@ -5,8 +5,7 @@ fingerprints.txt
PGP fingerprints of authoried release signers
standards.txt
Pointers to standards, RFC's and IETF Drafts that are
related to OpenSSL. Incomplete.
Moved to the web, https://www.openssl.org/docs/standards.html
HOWTO/
A few how-to documents; not necessarily up-to-date

107
doc/apps/CA.pl.pod
View File

@@ -1,35 +1,44 @@
=pod
=encoding utf8
=head1 NAME
CA.pl - friendlier interface for OpenSSL certificate programs
CA.pl - friendlier interface for GmSSL certificate programs
=head1 SYNOPSIS
B<CA.pl>
[B<-?>]
[B<-h>]
[B<-help>]
[B<-newcert>]
[B<-newreq>]
[B<-newreq-nodes>]
[B<-newca>]
[B<-xsign>]
[B<-sign>]
[B<-signreq>]
[B<-signcert>]
[B<-verify>]
[B<files>]
B<-?> |
B<-h> |
B<-help>
B<CA.pl>
B<-newcert> |
B<-newreq> |
B<-newreq-nodes> |
B<-xsign> |
B<-sign> |
B<-signCA> |
B<-signcert> |
B<-crl> |
B<-newca>
[B<-extra-cmd> extra-params]
B<CA.pl> B<-pkcs12> [B<-extra-pkcs12> extra-params] [B<certname>]
B<CA.pl> B<-verify> [B<-extra-verify> extra-params] B<certfile>...
B<CA.pl> B<-revoke> [B<-extra-ca> extra-params] B<certfile> [B<reason>]
=head1 DESCRIPTION
The B<CA.pl> script is a perl script that supplies the relevant command line
arguments to the B<openssl> command for some common certificate operations.
arguments to the B<gmssl> command for some common certificate operations.
It is intended to simplify the process of certificate creation and management
by the use of some simple options.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
@@ -41,15 +50,18 @@ prints a usage message.
creates a new self signed certificate. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
This argument invokes B<gmssl req> command.
=item B<-newreq>
creates a new certificate request. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
Executes B<gmssl req> command below the hood.
=item B<-newreq-nodes>
is like B<-newreq> except that the private key will not be encrypted.
Uses B<gmssl req> command.
=item B<-newca>
@@ -58,6 +70,7 @@ and B<-xsign> options). The user is prompted to enter the filename of the CA
certificates (which should also contain the private key) or by hitting ENTER
details of the CA will be prompted for. The relevant files and directories
are created in a directory called "demoCA" in the current directory.
B<gmssl req> and B<gmssl ca> commands are get invoked.
=item B<-pkcs12>
@@ -69,34 +82,55 @@ B<-sign> option. The PKCS#12 file can be imported directly into a browser.
If there is an additional argument on the command line it will be used as the
"friendly name" for the certificate (which is typically displayed in the browser
list box), otherwise the name "My Certificate" is used.
Delegates work to B<gmssl pkcs12> command.
=item B<-sign>, B<-signreq>, B<-xsign>
=item B<-sign>, B<-signcert>, B<-xsign>
calls the B<ca> program to sign a certificate request. It expects the request
to be in the file "newreq.pem". The new certificate is written to the file
"newcert.pem" except in the case of the B<-xsign> option when it is written
to standard output.
to standard output. Leverages B<gmssl ca> command.
=item B<-signCA>
this option is the same as the B<-signreq> option except it uses the configuration
file section B<v3_ca> and so makes the signed request a valid CA certificate. This
is useful when creating intermediate CA from a root CA.
Extra params are passed on to B<gmssl ca> command.
=item B<-signcert>
this option is the same as B<-sign> except it expects a self signed certificate
to be present in the file "newreq.pem".
Extra params are passed on to B<gmssl x509> and B<gmssl ca> commands.
=item B<-crl>
generate a CRL. Executes B<gmssl ca> command.
=item B<-revoke certfile [reason]>
revoke the certificate contained in the specified B<certfile>. An optional
reason may be specified, and must be one of: B<unspecified>,
B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
Leverages B<gmssl ca> command.
=item B<-verify>
verifies certificates against the CA certificate for "demoCA". If no certificates
are specified on the command line it tries to verify the file "newcert.pem".
are specified on the command line it tries to verify the file "newcert.pem".
Invokes B<gmssl verify> command.
=item B<files>
=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> <extra-params>
one or more optional certificate file names for use with the B<-verify> command.
The purpose of these parameters is to allow optional parameters to be supplied
to B<gmssl> that this command executes. The B<-extra-cmd> are specific to the
option being used and the B<gmssl> command getting invoked. For example
when this command invokes B<gmssl req> extra parameters can be passed on
with the B<-extra-req> parameter. The
B<gmssl> commands being invoked per option are documented below.
Users should consult B<gmssl> command documentation for more information.
=back
@@ -117,16 +151,16 @@ the request and finally create a PKCS#12 file containing it.
=head1 DSA CERTIFICATES
Although the B<CA.pl> creates RSA CAs and requests it is still possible to
use it with DSA certificates and requests using the L<req(1)|req(1)> command
use it with DSA certificates and requests using the L<req(1)> command
directly. The following example shows the steps that would typically be taken.
Create some DSA parameters:
openssl dsaparam -out dsap.pem 1024
gmssl dsaparam -out dsap.pem 1024
Create a DSA CA certificate and private key:
openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem
gmssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem
Create the CA directories and files:
@@ -137,7 +171,7 @@ enter cacert.pem when prompted for the CA file name.
Create a DSA certificate request and private key (a different set of parameters
can optionally be created first):
openssl req -out newreq.pem -newkey dsa:dsap.pem
gmssl req -out newreq.pem -newkey dsa:dsap.pem
Sign the request:
@@ -158,12 +192,12 @@ be wrong. In this case the command:
perl -S CA.pl
can be used and the B<OPENSSL_CONF> environment variable changed to point to
can be used and the B<OPENSSL_CONF> environment variable changed to point to
the correct path of the configuration file "openssl.cnf".
The script is intended as a simple front end for the B<openssl> program for use
The script is intended as a simple front end for the B<gmssl> program for use
by a beginner. Its behaviour isn't always what is wanted. For more control over the
behaviour of the certificate commands call the B<openssl> command directly.
behaviour of the certificate commands call the B<gmssl> command directly.
=head1 ENVIRONMENT VARIABLES
@@ -173,7 +207,16 @@ configuration file, not just its directory.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<req(1)|req(1)>, L<pkcs12(1)|pkcs12(1)>,
L<config(5)|config(5)>
L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>,
L<config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

75
doc/apps/asn1parse.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
asn1parse - ASN.1 parsing tool
=head1 SYNOPSIS
B<openssl> B<asn1parse>
B<gmssl> B<asn1parse>
[B<-help>]
[B<-inform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
@@ -20,6 +23,7 @@ B<openssl> B<asn1parse>
[B<-strparse offset>]
[B<-genstr string>]
[B<-genconf file>]
[B<-strictpem>]
=head1 DESCRIPTION
@@ -30,6 +34,10 @@ structures. It can also be used to extract data from ASN.1 formatted data.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform> B<DER|PEM>
the input format. B<DER> is binary format and B<PEM> (the default) is base64
@@ -82,36 +90,44 @@ option can be used multiple times to "drill down" into a nested structure.
=item B<-genstr string>, B<-genconf file>
generate encoded data based on B<string>, B<file> or both using
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. If B<file> only is
L<ASN1_generate_nconf(3)> format. If B<file> only is
present then the string is obtained from the default section using the name
B<asn1>. The encoded data is passed through the ASN1 parser and printed out as
though it came from a file, the contents can thus be examined and written to a
file using the B<out> option.
file using the B<out> option.
=item B<-strictpem>
If this option is used then B<-inform> will be ignored. Without this option any
data in a PEM format input file will be treated as being base64 encoded and
processed whether it has the normal PEM BEGIN and END markers or not. This
option will ignore any data prior to the start of the BEGIN marker, or after an
END marker in a PEM file.
=back
=head2 OUTPUT
=head2 Output
The output will typically contain lines like this:
0:d=0 hl=4 l= 681 cons: SEQUENCE
0:d=0 hl=4 l= 681 cons: SEQUENCE
.....
229:d=3 hl=3 l= 141 prim: BIT STRING
373:d=2 hl=3 l= 162 cons: cont [ 3 ]
376:d=3 hl=3 l= 159 cons: SEQUENCE
379:d=4 hl=2 l= 29 cons: SEQUENCE
229:d=3 hl=3 l= 141 prim: BIT STRING
373:d=2 hl=3 l= 162 cons: cont [ 3 ]
376:d=3 hl=3 l= 159 cons: SEQUENCE
379:d=4 hl=2 l= 29 cons: SEQUENCE
381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier
386:d=5 hl=2 l= 22 prim: OCTET STRING
410:d=4 hl=2 l= 112 cons: SEQUENCE
386:d=5 hl=2 l= 22 prim: OCTET STRING
410:d=4 hl=2 l= 112 cons: SEQUENCE
412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier
417:d=5 hl=2 l= 105 prim: OCTET STRING
524:d=4 hl=2 l= 12 cons: SEQUENCE
417:d=5 hl=2 l= 105 prim: OCTET STRING
524:d=4 hl=2 l= 12 cons: SEQUENCE
.....
This example is part of a self signed certificate. Each line starts with the
This example is part of a self-signed certificate. Each line starts with the
offset in decimal. B<d=XX> specifies the current depth. The depth is increased
within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
(tag and length octets) of the current type. B<l=XX> gives the length of
@@ -119,49 +135,49 @@ the contents octets.
The B<-i> option can be used to make the output more readable.
Some knowledge of the ASN.1 structure is needed to interpret the output.
Some knowledge of the ASN.1 structure is needed to interpret the output.
In this example the BIT STRING at offset 229 is the certificate public key.
The contents octets of this will contain the public key information. This can
be examined using the option B<-strparse 229> to yield:
0:d=0 hl=3 l= 137 cons: SEQUENCE
0:d=0 hl=3 l= 137 cons: SEQUENCE
3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
135:d=1 hl=2 l= 3 prim: INTEGER :010001
=head1 NOTES
If an OID is not part of OpenSSL's internal table it will be represented in
numerical form (for example 1.2.3.4). The file passed to the B<-oid> option
If an OID is not part of GmSSL's internal table it will be represented in
numerical form (for example 1.2.3.4). The file passed to the B<-oid> option
allows additional OIDs to be included. Each line consists of three columns,
the first column is the OID in numerical format and should be followed by white
space. The second column is the "short name" which is a single word followed
by white space. The final column is the rest of the line and is the
"long name". B<asn1parse> displays the long name. Example:
C<1.2.3.4 shortName A long name>
C<1.2.3.4 shortName A long name>
=head1 EXAMPLES
Parse a file:
openssl asn1parse -in file.pem
gmssl asn1parse -in file.pem
Parse a DER file:
openssl asn1parse -inform DER -in file.der
gmssl asn1parse -inform DER -in file.der
Generate a simple UTF8String:
openssl asn1parse -genstr 'UTF8:Hello World'
gmssl asn1parse -genstr 'UTF8:Hello World'
Generate and write out a UTF8String, don't print parsed output:
openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der
gmssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der
Generate using a config file:
openssl asn1parse -genconf asn1.cnf -noout -out asn1.der
gmssl asn1parse -genconf asn1.cnf -noout -out asn1.der
Example config file:
@@ -180,6 +196,15 @@ ASN.1 types is not well handled (if at all).
=head1 SEE ALSO
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
L<ASN1_generate_nconf(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

114
doc/apps/c_rehash.pod
View File

@@ -1,114 +0,0 @@
=pod
=for comment
Original text by James Westby, contributed under the OpenSSL license.
=head1 NAME
c_rehash - Create symbolic links to files named by the hash values
=head1 SYNOPSIS
B<c_rehash>
B<[-old]>
B<[-h]>
B<[-n]>
B<[-v]>
[ I<directory>...]
=head1 DESCRIPTION
B<c_rehash> scans directories and calculates a hash value of each
C<.pem>, C<.crt>, C<.cer>, or C<.crl>
file in the specified directory list and creates symbolic links
for each file, where the name of the link is the hash value.
(If the platform does not support symbolic links, a copy is made.)
This utility is useful as many programs that use OpenSSL require
directories to be set up like this in order to find certificates.
If any directories are named on the command line, then those are
processed in turn. If not, then the B<SSL_CERT_DIR> environment variable
is consulted; this shold be a colon-separated list of directories,
like the Unix B<PATH> variable.
If that is not set then the default directory (installation-specific
but often B</usr/local/ssl/certs>) is processed.
In order for a directory to be processed, the user must have write
permissions on that directory, otherwise it will be skipped.
The links created are of the form C<HHHHHHHH.D>, where each B<H>
is a hexadecimal character and B<D> is a single decimal digit.
When processing a directory, B<c_rehash> will first remove all links
that have a name in that syntax. If you have links in that format
used for other purposes, they will be removed.
To skip the removal step, use the B<-n> flag.
Hashes for CRL's look similar except the letter B<r> appears after
the period, like this: C<HHHHHHHH.rD>.
Multiple objects may have the same hash; they will be indicated by
incrementing the B<D> value. Duplicates are found by comparing the
full SHA-1 fingerprint. A warning will be displayed if a duplicate
is found.
A warning will also be displayed if there are files that
cannot be parsed as either a certificate or a CRL.
The program uses the B<openssl> program to compute the hashes and
fingerprints. If not found in the user's B<PATH>, then set the
B<OPENSSL> environment variable to the full pathname.
Any program can be used, it will be invoked as follows for either
a certificate or CRL:
$OPENSSL x509 -hash -fingerprint -noout -in FILENAME
$OPENSSL crl -hash -fingerprint -noout -in FILENAME
where B<FILENAME> is the filename. It must output the hash of the
file on the first line, and the fingerprint on the second,
optionally prefixed with some text and an equals sign.
=head1 OPTIONS
=over 4
=item B<-old>
Use old-style hashing (MD5, as opposed to SHA-1) for generating
links for releases before 1.0.0. Note that current versions will
not use the old style.
=item B<-h>
Display a brief usage message.
=item B<-n>
Do not remove existing links.
This is needed when keeping new and old-style links in the same directory.
=item B<-v>
Print messages about old links removed and new links created.
By default, B<c_rehash> only lists each directory as it is processed.
=back
=head1 ENVIRONMENT
=over
=item B<OPENSSL>
The path to an executable to use to generate hashes and
fingerprints (see above).
=item B<SSL_CERT_DIR>
Colon separated list of directories to operate on.
Ignored if directories are listed on the command line.
=back
=head1 SEE ALSO
L<openssl(1)|openssl(1)>,
L<crl(1)|crl(1)>.
L<x509(1)|x509(1)>.

298
doc/apps/ca.pod
View File

@@ -1,18 +1,21 @@
=pod
=encoding utf8
=head1 NAME
ca - sample minimal CA application
=head1 SYNOPSIS
B<openssl> B<ca>
B<gmssl> B<ca>
[B<-help>]
[B<-verbose>]
[B<-config filename>]
[B<-name section>]
[B<-gencrl>]
[B<-revoke file>]
[B<-valid file>]
[B<-status serial>]
[B<-updatedb>]
[B<-crl_reason reason>]
@@ -49,6 +52,7 @@ B<openssl> B<ca>
[B<-engine id>]
[B<-subj arg>]
[B<-utf8>]
[B<-create_serial>]
[B<-multivalue-rdn>]
=head1 DESCRIPTION
@@ -60,27 +64,50 @@ and their status.
The options descriptions will be divided into each purpose.
=head1 CA OPTIONS
ca指令是CA中很小的应用。它可以用来签发各种形式的用户证书并产生CRL。它还可以用来更新证书库。
在这些指令的介绍中，将尽可能地对它们进行分类介绍。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
显示用法信息。
=item B<-verbose>
this prints extra details about the operations being performed.
输出更详细的一些操作过程信息。
=item B<-config filename>
specifies the configuration file to use.
指定将要使用的配置文件。
=item B<-name section>
specifies the configuration file section to use (overrides
B<default_ca> in the B<ca> section).
指定将要使用的配置文件部分（覆盖ca部分中的default_ca部分）
=item B<-in filename>
an input filename containing a single certificate request to be
signed by the CA.
一个输入文件名包含了一个要由CA签名的单独证书请求。
=item B<-ss_cert filename>
a single self signed certificate to be signed by the CA.
a single self-signed certificate to be signed by the CA.
一个要由CA签名的自签名证书。
=item B<-spkac filename>
@@ -88,10 +115,15 @@ a file containing a single Netscape signed public key and challenge
and additional field values to be signed by the CA. See the B<SPKAC FORMAT>
section for information on the required input and output format.
一个包含了一个单独的Netscape签名的公钥和其他附加用户信息。
关于输入输出格式的信息具体可以参考SPKAC部分。
=item B<-infiles>
if present this should be the last option, all subsequent arguments
are assumed to the the names of files containing certificate requests.
are taken as the names of files containing certificate requests.
该选项总是作为指令的最后一个选项，其后面所有的参数都被认为是证书请求文件。
=item B<-out filename>
@@ -99,36 +131,48 @@ the output file to output certificates to. The default is standard
output. The certificate details will also be printed out to this
file in PEM format (except that B<-spkac> outputs DER format).
输出文件输出签发好的证书。默认值为标准输出。输出的证书都是PEM编码的（除了spkac输出DER编码）
=item B<-outdir directory>
the directory to output certificates to. The certificate will be
written to a filename consisting of the serial number in hex with
".pem" appended.
将新生成的证书输出到目录。新生成证书将会序列号加“pem”后缀成为一个完整的证书文件名。
=item B<-cert>
the CA certificate file.
CA证书文件。
=item B<-keyfile filename>
the private key to sign requests with.
用于签署请求的私钥。
=item B<-keyform PEM|DER>
the format of the data in the private key file.
The default is PEM.
私钥文件中数据的格式。默认为PEM。
=item B<-key password>
the password used to encrypt the private key. Since on some
systems the command line arguments are visible (e.g. Unix with
the 'ps' utility) this option should be used with caution.
用于加密私钥的密码。因为在某些系统上命令行参数是可见的（例如使用“ps”实用程序的Unix），应谨慎使用此指令。
=item B<-selfsign>
indicates the issued certificates are to be signed with the key
the certificate requests were signed with (given with B<-keyfile>).
Cerificate requests signed with a different key are ignored. If
Certificate requests signed with a different key are ignored. If
B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
ignored.
@@ -138,38 +182,54 @@ certificate appears among the entries in the certificate database
serial number counter as all other certificates sign with the
self-signed certificate.
表示发出的证书将使用证书请求签名的密钥（以-keyfile命名）进行签名。
使用不同密钥签名的证书请求将被忽略。如果给出-spkac，-ss_cert或-gencrl，则忽略-selfsign
使用-selfsign的结果是自签名证书出现在证书数据库的条目中，并使用与其他证书相同的序列号计数器。
=item B<-passin arg>
the 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-verbose>
this prints extra details about the operations being performed.
给定了读取私钥文件的时候需要提供的口令。
=item B<-notext>
don't output the text form of a certificate to the output file.
不把证书的文本形式输出到输出文件。
=item B<-startdate date>
this allows the start date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
设置证书的生效时间，其参数格式是“YYMMDDHHMMSSZ”。
=item B<-enddate date>
this allows the expiry date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
设置证书的到期时间，其参数格式是“YYMMDDHHMMSSZ”。
=item B<-days arg>
the number of days to certify the certificate for.
设置证书的有效天数。
=item B<-md alg>
the message digest to use. Possible values include md5, sha1 and mdc2.
the message digest to use.
Any digest supported by the GmSSL B<dgst> command can be used.
This option also applies to CRLs.
消息摘要使用。
可以使用GmSSL dgst命令支持的任何摘要。
该选项也适用于CRLs。
=item B<-policy arg>
this option defines the CA "policy" to use. This is a section in
@@ -177,6 +237,9 @@ the configuration file which decides which fields should be mandatory
or match the CA certificate. Check out the B<POLICY FORMAT> section
for more information.
该选项定义了CA的匹配策略。这是配置文件中的一部分，它决定了哪些字段应该是必须的
或与CA证书匹配。查看policy format部分来了解更多信息。
=item B<-msie_hack>
this is a legacy option to make B<ca> work with very old versions of
@@ -185,14 +248,22 @@ for almost everything. Since the old control has various security bugs
its use is strongly discouraged. The newer control "Xenroll" does not
need this option.
这是一个遗留的项目，它可以使ca可以使用非常老的ie证书注册控件centenr3.它几乎所有东西
都使用了UniversalStrings。我们非常不推荐使用旧版控件应为它有很多的安全漏洞。新的控件
Xenroll不需要这一项。
=item B<-preserveDN>
Normally the DN order of a certificate is the same as the order of the
fields in the relevant policy section. When this option is set the order
fields in the relevant policy section. When this option is set the order
is the same as the request. This is largely for compatibility with the
older IE enrollment control which would only accept certificates if their
DNs match the order of the request. This is not needed for Xenroll.
使指令在签发证书的时候让证书主体名称内的各项内容顺序跟证书请求中的顺序保持一致。
而在默认情况下，证书主题名称内的各个选项顺序是按照配置文件中的证书匹配策略子段的
选项顺序进行排列的。
=item B<-noemailDN>
The DN of a certificate can contain the EMAIL field if present in the
@@ -202,11 +273,17 @@ EMAIL field is removed from the certificate' subject and set only in
the, eventually present, extensions. The B<email_in_dn> keyword can be
used in the configuration file to enable this behaviour.
一个证书的主体名称可以包含E-mail项目，但是将电子邮件放在主体别名中会更好一点。
当你启用这个选项后e-mail会从证书主体名称移除并最终设在主体别名中。
可以在配置文件中使用email_in_dn来启用这个行为。
=item B<-batch>
this sets the batch mode. In this mode no questions will be asked
and all certificates will be certified automatically.
该选项设定batch模式。在这一模式中ca指令不提示用户输入任何信息而直接签发所有输入的证书请求。
=item B<-extensions section>
the section of the configuration file containing certificate extensions
@@ -214,15 +291,21 @@ to be added when a certificate is issued (defaults to B<x509_extensions>
unless the B<-extfile> option is used). If no extension section is
present then, a V1 certificate is created. If the extension section
is present (even if it is empty), then a V3 certificate is created. See the:w
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
L<x509v3_config(5)> manual page for details of the
extension section format.
配置文件部分包含了颁发证书时要添加的证书扩展名（默认为x509_extensions,除非使用-extfile选项）。
如果没有扩展部分，则创建V1证书。如果存在扩展部分（即使该部分为空），则创建V3证书。
有关扩展部分格式的详细信息，请参阅x509v3_config（5）手册页。
=item B<-extfile file>
an additional configuration file to read certificate extensions from
(using the default section unless the B<-extensions> option is also
used).
一个专门用来保存X.509 v3扩展项信息的文件。
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<ca>
@@ -230,25 +313,42 @@ 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.
指定一个引擎（通过其唯一的id字符串）会导致ca尝试获取对指定engine设备的功能引用
并进行初始化如果需要。这个engine将被设置为所有可用算法的默认。
=item B<-subj arg>
supersedes subject name given in the request.
The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
重新填写用户的证书主体名称。subj选项的参数格式为/type0=value0/type1=value1/type2...，字符可能会被\转义，空格不被跳过。
=item B<-utf8>
this option causes field values to be interpreted as UTF8 strings, by
this option causes field values to be interpreted as UTF8 strings, by
default they are interpreted as ASCII. This means that the field
values, whether prompted from a terminal or obtained from a
configuration file, must be valid UTF8 strings.
这一选项字段值转为UTF8字符串，默认情况下为ASCII。这意味着字段值（无论从终端提示还是从配置文件获取）都必须是有效的UTF8字符串。
=item B<-create_serial>
if reading serial from the text file as specified in the configuration
fails, specifying this option creates a new random serial to be used as next
serial number.
如果从配置中指定的文本文件读取序列失败，该选项可以创造一个新的随机序列作为下一个序列号。
=item B<-multivalue-rdn>
this option causes the -subj argument to be interpretedt with full
This option causes the -subj argument to be interpreted with full
support for multivalued RDNs. Example:
I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
该选项可以解释-subj参数，并完全支持多RND。
I</DC=org/DC=GmSSL/DC=users/UID=123456+CN=John Doe>
If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
@@ -262,28 +362,46 @@ If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
this option generates a CRL based on information in the index file.
该选项用于生成一个基于索引文件信息的CFL，
=item B<-crldays num>
the number of days before the next CRL is due. That is the days from
now to place in the CRL nextUpdate field.
以“天”为单位设置CRL的有效期。
=item B<-crlhours num>
the number of hours before the next CRL is due.
以小时为单位设置CRL有效期。
=item B<-revoke filename>
a filename containing a certificate to revoke.
一个包含要撤销的证书的文件名
=item B<-valid filename>
a filename containing a certificate to add a Valid certificate entry.
一个包含添加有效证书条目的证书的文件名。
=item B<-status serial>
displays the revocation status of the certificate with the specified
serial number and exits.
显示具有指定序列号的证书的撤销状态并退出。
=item B<-updatedb>
Updates the database index to purge expired certificates.
更新数据库索引清除以过期的证书。
=item B<-crl_reason reason>
revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
@@ -291,9 +409,13 @@ B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
insensitive. Setting any revocation reason will make the CRL v2.
In practive B<removeFromCRL> is not particularly useful because it is only used
In practice B<removeFromCRL> is not particularly useful because it is only used
in delta CRLs which are not currently implemented.
撤销原因，其中的原因有：未指定，key妥协，CA妥协，联系改变，superseded，cessationofoperation，insensitive。设置任何撤销原因将使CRL变成v2.
实际上，removeFromCRL不是特别有用因为，因为它仅用于当前未实现的deltaCRL。
=item B<-crl_hold instruction>
This sets the CRL revocation reason code to B<certificateHold> and the hold
@@ -301,16 +423,23 @@ instruction to B<instruction> which must be an OID. Although any OID can be
used only B<holdInstructionNone> (the use of which is discouraged by RFC2459)
B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used.
这会将CRL撤销原因代码设置为certificatehold，并将指令的保持指令设置为必须是OID的指令。
虽然任何OID只能使用holdInstructionNone*RFC2459不鼓励使用它），但通常会使用holdInstructionCallIssuer或holdInstruvtionReject。
=item B<-crl_compromise time>
This sets the revocation reason to B<keyCompromise> and the compromise time to
B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>.
将撤销原因设置为keyCompromise并将妥协时间设为time。time应为广义时间格式：YYYYMMDDHHMMSSZ。
=item B<-crl_CA_compromise time>
This is the same as B<crl_compromise> except the revocation reason is set to
B<CACompromise>.
该选项与crl_compromise一样，除了撤销原因是CACompromise。
=item B<-crlexts section>
the section of the configuration file containing CRL extensions to
@@ -319,9 +448,11 @@ created, if the CRL extension section is present (even if it is
empty) then a V2 CRL is created. The CRL extensions specified are
CRL extensions and B<not> CRL entry extensions. It should be noted
that some software (for example Netscape) can't handle V2 CRLs. See
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
L<x509v3_config(5)> manual page for details of the
extension section format.
这部分包含CRL扩展的配置文件。 如果不存在CRL扩展部分，则创建V1 CRL，如果存在CRL扩展部分（即使为空），则创建V2 CRL。 指定的CRL扩展是CRL扩展，而不是CRL条目扩展。 应该注意的是，某些软件（例如Netscape）无法处理V2 CRL。 有关扩展部分格式的详细信息，请参阅x509v3_config（5）手册页。
=back
=head1 CONFIGURATION FILE OPTIONS
@@ -346,6 +477,10 @@ option is described as mandatory then it must be present in
the configuration file or the command line equivalent (if
any) used.
包含ca选项的配置文件部分如下所示：如果使用-name命令行选项，则命名要使用的部分。 否则要使用的部分必须在配置文件（或配置文件的默认部分）的ca部分的default_ca选项中命名。 除了default_ca，以下选项直接从ca部分读取：RANDFILE preserve msie_hack除了RANDFILE之外，这可能是一个错误，可能会在将来的版本中更改。
许多配置文件选项与命令行选项相同。 在配置文件和命令行中存在选项的地方，使用命令行值。 在某个选项被描述为强制性的情况下，它必须存在于配置文件或命令行等效（如果有的话）中。
=over 4
=item B<oid_file>
@@ -353,7 +488,10 @@ any) used.
This specifies a file containing additional B<OBJECT IDENTIFIERS>.
Each line of the file should consist of the numerical form of the
object identifier followed by white space then the short name followed
by white space and finally the long name.
by white space and finally the long name.
这指定一个包含其他对象标识符的文件。 文件的每一行应由对象标识符的数字形式组成
，后跟空格，短名称后跟空格，最后是长名称。
=item B<oid_section>
@@ -362,105 +500,147 @@ object identifiers. Each line should consist of the short name of the
object identifier followed by B<=> and the numerical form. The short
and long names are the same when this option is used.
这指定了配置文件中包含额外对象标识符的部分。 每一行都应该包含对象标识符的短名称，
后面是=和数字形式。 当使用此选项时，短名称和长名称相同。
=item B<new_certs_dir>
the same as the B<-outdir> command line option. It specifies
the directory where new certificates will be placed. Mandatory.
与-outdir命令行选项相同。 它指定将放置新证书的目录。强制性。
=item B<certificate>
the same as B<-cert>. It gives the file containing the CA
certificate. Mandatory.
与-cert命令行选项相同。它给出包含CA证书的文件。强制性。
=item B<private_key>
same as the B<-keyfile> option. The file containing the
CA private key. Mandatory.
与-keyfile选项相同。文件包含CA私钥。强制性。
=item B<RANDFILE>
a file used to read and write random number seed information, or
an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
an EGD socket (see L<RAND_egd(3)>).
用于读取和写入随机数种子信息的文件，或EGD套接字（请参阅RAND_egd（3））。
=item B<default_days>
the same as the B<-days> option. The number of days to certify
a certificate for.
a certificate for.
和-days相同。认证证书的天数。
=item B<default_startdate>
the same as the B<-startdate> option. The start date to certify
a certificate for. If not set the current time is used.
和-startdate相同。认证证书的开始日期。 如果未设置，则使用当前时间。
=item B<default_enddate>
the same as the B<-enddate> option. Either this option or
B<default_days> (or the command line equivalents) must be
present.
和-enddate相同。该选项或default_days（或命令行等效项）必须存在。
=item B<default_crl_hours default_crl_days>
the same as the B<-crlhours> and the B<-crldays> options. These
will only be used if neither command line option is present. At
least one of these must be present to generate a CRL.
与-crlhours和-crldays选项一样。 只有在命令行选项不存在的情况下才会使用这些。 必须至少有一个必须存在才能生成CRL。
=item B<default_md>
the same as the B<-md> option. The message digest to use. Mandatory.
the same as the B<-md> option. Mandatory.
和-md一样。强制性。
=item B<database>
the text database file to use. Mandatory. This file must be present
though initially it will be empty.
要使用的文本数据库文件。强制性。该文件必须存在但一开始它是空的。
=item B<unique_subject>
if the value B<yes> is given, the valid certificate entries in the
database must have unique subjects. if the value B<no> is given,
several valid certificate entries may have the exact same subject.
The default value is B<yes>, to be compatible with older (pre 0.9.8)
versions of OpenSSL. However, to make CA certificate roll-over easier,
versions of GmSSL. However, to make CA certificate roll-over easier,
it's recommended to use the value B<no>, especially if combined with
the B<-selfsign> command line option.
如果给出值yes，则数据库中的有效证书条目必须具有唯一主题。 如果给出值no，几个有效的证书条目可能具有完全相同的主题。 默认值为yes，与GmSSL的旧版（0.9.8）版本兼容。 但是，为了使CA证书转换更容易，建议使用值no，特别是如果与-selfsign命令行选项相结合。
=item B<serial>
a text file containing the next serial number to use in hex. Mandatory.
This file must be present and contain a valid serial number.
一个包含了下一个要使用序列号的十六进制文本文件。强制性。
该文件必须存在并包含有效的序列号。
=item B<crlnumber>
a text file containing the next CRL number to use in hex. The crl number
will be inserted in the CRLs only if this file exists. If this file is
present, it must contain a valid CRL number.
包含用于十六进制的下一个CRL编号的文本文件。 只有当此文件存在时，crl号才会插入到CRL中。 如果此文件存在，它必须包含有效的CRL号码。
=item B<x509_extensions>
the same as B<-extensions>.
和-extensions一样
=item B<crl_extensions>
the same as B<-crlexts>.
和-crlexts一样
=item B<preserve>
the same as B<-preserveDN>
和-peserveDN一样
=item B<email_in_dn>
the same as B<-noemailDN>. If you want the EMAIL field to be removed
from the DN of the certificate simply set this to 'no'. If not present
the default is to allow for the EMAIL filed in the certificate's DN.
the default is to allow for the EMAIL field in the certificate's DN.
和-noemailDN一样。如果您希望将EMAIL字段从证书的DN中删除，请将其设置为“否”。 如果不存在，默认值是允许证书的DN中的EMAIL字段。
=item B<msie_hack>
the same as B<-msie_hack>
和-msie_hack一样
=item B<policy>
the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
for more information.
和-policy一样。强制性。更多详情请参考POLICY FORMAT部分。
=item B<name_opt>, B<cert_opt>
these options allow the format used to display the certificate details
@@ -474,10 +654,16 @@ For convenience the values B<ca_default> are accepted by both to produce
a reasonable output.
If neither option is present the format used in earlier versions of
OpenSSL is used. Use of the old format is B<strongly> discouraged because
GmSSL is used. Use of the old format is B<strongly> discouraged because
it only displays fields mentioned in the B<policy> section, mishandles
multicharacter string types and does not display extensions.
这些选项允许在询问用户确认签名时用于显示证书详细信息的格式。 x509 utilities -nameopt和-certopt开关支持的所有选项可以在这里使用，除了no_signame和no_sigdump被永久设置并且不能禁用（这是因为证书签名无法显示，因为证书尚未在此签名 点）。
为方便起见，ca_default值被两者接受以产生合理的输出。
如果两个选项不存在，则使用早期版本的GmSSL中使用的格式。 强烈建议不要使用旧格式，因为它仅显示策略部分中提及的字段，处理多字符串字符串类型，并且不显示扩展名。
=item B<copy_extensions>
determines how extensions in certificate requests should be handled.
@@ -492,6 +678,11 @@ using this option.
The main use of this option is to allow a certificate request to supply
values for certain extensions such as subjectAltName.
确定如何处理证书请求中的扩展。 如果设置为none或此选项不存在，则扩展名将被忽略，不会复制到证书。 如果设置为复制，请求中存在的任何尚未存在的扩展名将复制到证书。 如果设置为copyall，则请求中的所有扩展都将复制到证书中：如果扩展名已经存在于证书中，则首先将其删除。 使用此选项之前，请参阅警告部分。
此选项的主要用途是允许证书请求为某些扩展名（如subjectAltName）提供值。
=back
=head1 POLICY FORMAT
@@ -508,7 +699,7 @@ this can be regarded more of a quirk than intended behaviour.
The input to the B<-spkac> command line option is a Netscape
signed public key and challenge. This will usually come from
the B<KEYGEN> tag in an HTML form to create a new private key.
the B<KEYGEN> tag in an HTML form to create a new private key.
It is however possible to create SPKACs using the B<spkac> utility.
The file should contain the variable SPKAC set to the value of
@@ -538,48 +729,48 @@ demoCA/index.txt.
Sign a certificate request:
openssl ca -in req.pem -out newcert.pem
gmssl ca -in req.pem -out newcert.pem
Sign a certificate request, using CA extensions:
openssl ca -in req.pem -extensions v3_ca -out newcert.pem
gmssl ca -in req.pem -extensions v3_ca -out newcert.pem
Generate a CRL
openssl ca -gencrl -out crl.pem
gmssl ca -gencrl -out crl.pem
Sign several requests:
openssl ca -infiles req1.pem req2.pem req3.pem
gmssl ca -infiles req1.pem req2.pem req3.pem
Certify a Netscape SPKAC:
openssl ca -spkac spkac.txt
gmssl ca -spkac spkac.txt
A sample SPKAC file (the SPKAC line has been truncated for clarity):
SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
CN=Steve Test
emailAddress=steve@openssl.org
0.OU=OpenSSL Group
emailAddress=steve@gmssl.org
0.OU=GmSSL Group
1.OU=Another Group
A sample configuration file with the relevant sections for B<ca>:
[ ca ]
default_ca = CA_default # The default ca section
[ CA_default ]
dir = ./demoCA # top dir
database = $dir/index.txt # index file.
new_certs_dir = $dir/newcerts # new certs dir
new_certs_dir = $dir/newcerts # new certs dir
certificate = $dir/cacert.pem # The CA cert
serial = $dir/serial # serial no file
private_key = $dir/private/cakey.pem# CA private key
RANDFILE = $dir/private/.rand # random number file
default_days = 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md = md5 # md to use
@@ -587,9 +778,9 @@ A sample configuration file with the relevant sections for B<ca>:
policy = policy_any # default policy
email_in_dn = no # Don't add the email into cert DN
name_opt = ca_default # Subject name display option
cert_opt = ca_default # Certificate display option
copy_extensions = none # Don't copy extensions from request
name_opt = ca_default # Subject name display option
cert_opt = ca_default # Certificate display option
copy_extensions = none # Don't copy extensions from request
[ policy_any ]
countryName = supplied
@@ -623,7 +814,7 @@ be overridden by the B<-config> command line option.
=head1 RESTRICTIONS
The text database index file is a critical part of the process and
The text database index file is a critical part of the process and
if corrupted it can be difficult to fix. It is theoretically possible
to rebuild the index file from all the issued certificates and a current
CRL: however there is no option to do this.
@@ -631,18 +822,18 @@ CRL: however there is no option to do this.
V2 CRL features like delta CRLs are not currently supported.
Although several requests can be input and handled at once it is only
possible to include one SPKAC or self signed certificate.
possible to include one SPKAC or self-signed certificate.
=head1 BUGS
The use of an in memory text database can cause problems when large
The use of an in-memory text database can cause problems when large
numbers of certificates are present because, as the name implies
the database has to be kept in memory.
The B<ca> command really needs rewriting or the required functionality
exposed at either a command or interface level so a more friendly utility
(perl script or GUI) can handle things properly. The scripts B<CA.sh> and
B<CA.pl> help a little but not very much.
(perl script or GUI) can handle things properly. The script
B<CA.pl> helps a little but not very much.
Any fields in a request that are not present in a policy are silently
deleted. This does not happen if the B<-preserveDN> option is used. To
@@ -651,7 +842,7 @@ RFCs, regardless the contents of the request' subject the B<-noemailDN>
option can be used. The behaviour should be more friendly and
configurable.
Cancelling some commands by refusing to certify a certificate can
Canceling some commands by refusing to certify a certificate can
create an empty file.
=head1 WARNINGS
@@ -670,7 +861,7 @@ The B<copy_extensions> option should be used with caution. If care is
not taken then it can be a security risk. For example if a certificate
request contains a basicConstraints extension with CA:TRUE and the
B<copy_extensions> value is set to B<copyall> and the user does not spot
this when the certificate is displayed then this will hand the requestor
this when the certificate is displayed then this will hand the requester
a valid CA certificate.
This situation can be avoided by setting B<copy_extensions> to B<copy>
@@ -690,7 +881,16 @@ then even if a certificate is issued with CA:TRUE it will not be valid.
=head1 SEE ALSO
L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
L<config(5)|config(5)>, L<x509v3_config(5)|x509v3_config(5)>
L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
L<config(5)>, L<x509v3_config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

666
doc/apps/ciphers.pod
View File

@@ -1,60 +1,148 @@
=pod
=encoding utf8
=head1 NAME
ciphers - SSL cipher display and cipher list tool.
ciphers - SSL cipher display and cipher list tool
=head1 SYNOPSIS
B<openssl> B<ciphers>
B<gmssl> B<ciphers>
[B<-help>]
[B<-s>]
[B<-v>]
[B<-V>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-tls1_3>]
[B<-s>]
[B<-psk>]
[B<-srp>]
[B<-stdname>]
[B<cipherlist>]
=head1 DESCRIPTION
The B<ciphers> command converts textual OpenSSL cipher lists into ordered
The B<ciphers> command converts textual GmSSL cipher lists into ordered
SSL cipher preference lists. It can be used as a test tool to determine
the appropriate cipherlist.
=head1 COMMAND OPTIONS
ciphers命令将GmSSL文本密码列表转换成有序的SSL密码偏好列表。它可以用作测试工具
来决定适当的密码列表。
=head1 OPTIONS
=over 4
=item B<-help>
Print a usage message.
打印使用信息。
=item B<-s>
Only list supported ciphers: those consistent with the security level, and
minimum and maximum protocol version. This is closer to the actual cipher list
an application will support.
PSK and SRP ciphers are not enabled by default: they require B<-psk> or B<-srp>
to enable them.
It also does not change the default list of supported signature algorithms.
On a server the list of supported ciphers might also exclude other ciphers
depending on the configured certificates and presence of DH parameters.
If this option is not used then all ciphers that match the cipherlist will be
listed.
只列出了支持的密码：那些与安全级别一致的密码，最小和最大的协议版本。
这更接近应用程序将支持的实际密码列表。
默认情况下，PSK和SRP密码未启用
它也不会更改支持的签名算法的默认列表。
在服务器上，支持的密码列表也可能会根据配置的证书和DH参数的存在来排除其他密码。
如果不使用此选项，则将列出与密码列表匹配的所有密码。
=item B<-psk>
When combined with B<-s> includes cipher suites which require PSK.
当与-s组合时包含了需要PSK的密码套件。
=item B<-srp>
When combined with B<-s> includes cipher suites which require SRP.
当与-s组合时包含了需要SRP的密码套件。
=item B<-v>
Verbose option. List ciphers with a complete description of
protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange,
authentication, encryption and mac algorithms used along with any key size
restrictions and whether the algorithm is classed as an "export" cipher.
Note that without the B<-v> option, ciphers may seem to appear twice
in a cipher list; this is when similar ciphers are available for
SSL v2 and for SSL v3/TLS v1.
Verbose output: For each ciphersuite, list details as provided by
L<SSL_CIPHER_description(3)>.
详细的列出所有加密套件。
=item B<-V>
Like B<-v>, but include cipher suite codes in output (hex format).
Like B<-v>, but include the official cipher suite values in hex.
=item B<-ssl3>, B<-tls1>
和-v相似，但包含十六进制官方密码套件。
This lists ciphers compatible with any of SSLv3, TLSv1, TLSv1.1 or TLSv1.2.
=item B<-tls1_3>
=item B<-ssl2>
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1.3 were negotiated.
Only include SSLv2 ciphers.
结合了-s选项。列出了如果TVSv1.3达成协议要使用的密码。
=item B<-h>, B<-?>
=item B<-tls1_2>
Print a brief usage message.
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1.2 were negotiated.
结合了-s选项。列出了如果TVSv1.2达成协议要使用的密码。
=item B<-ssl3>
In combination with the B<-s> option, list the ciphers which would be used if
SSLv3 were negotiated.
结合了-s选项。列出了如果SSLv3达成协议要使用的密码。
=item B<-tls1>
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1 were negotiated.
结合了-s选项。列出了如果TVSv1达成协议要使用的密码。
=item B<-tls1_1>
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1.1 were negotiated.
结合了-s选项。列出了如果TVSv1.1达成协议要使用的密码。
=item B<-stdname>
precede each ciphersuite by its standard name: only available is GmSSL
is built with tracing enabled (B<enable-ssl-trace> argument to Configure).
在每个密码套件之前加上其标准名称：只有可用的GmSSL是使用跟踪启用（enable-ssl-trace参数配置）构建的。
=item B<cipherlist>
A cipher list to convert to a cipher preference list. If it is not included
a cipher list to convert to a cipher preference list. If it is not included
then the default cipher list will be used. The format is described below.
一个用于转换为密码偏好列表的密码表。如果不包括，那么将使用默认密码列表。格式如下所述。
=back
=head1 CIPHER LIST FORMAT
@@ -94,8 +182,35 @@ as a list of ciphers to be appended to the current preference list. If the
list includes any ciphers already present they will be ignored: that is they
will not moved to the end of the list.
Additionally the cipher string B<@STRENGTH> can be used at any point to sort
the current cipher list in order of encryption algorithm key length.
The cipher string B<@STRENGTH> can be used at any point to sort the current
cipher list in order of encryption algorithm key length.
The cipher string B<@SECLEVEL=n> can be used at any point to set the security
level to B<n>.
密码列表由一个或多个由冒号分隔的密码串组成。逗号或空格也是可接受的分隔符，但通常使用冒号。
实际的密码串可以采取几种不同的形式。
它可以由单个加密套件组成，如RC4-SHA。
它可以表示包含某种算法或某种类型的密码套件的密码套件列表。例如，SHA1表示使用摘要算法SHA1的所有密码套件，SSLv3表示所有SSL v3算法。
密码套件列表可以使用+字符组合在单个密码字符串中。这被用作逻辑和操作。例如，SHA1 + DES表示包含SHA1和DES算法的所有密码套件。
每个密码字符串都可以前面加上字符！， - 或+。
如果！然后使用密码从列表中永久删除。删除的密码永远不会重新出现在列表中，即使它们被明确声明。
如果使用，则从列表中删除密码，但是可以通过稍后的选项再次添加一些或所有密码。
如果使用+，则将密码移动到列表的末尾。此选项不会添加任何新的密码，它只是移动匹配现有的密码。
如果这些字符都不存在，则该字符串将被解释为要附加到当前偏好列表的密码列表。如果列表中包含已经存在的任何密码，那么它们将被忽略：它们不会移动到列表的末尾。
可以在任何时候使用密码字符串@STRENGTH按照加密算法密钥长度的顺序对当前密码列表进行排序。
可以在任何时候使用密码字符串@ SECLEVEL = n来将安全级别设置为n。
=head1 CIPHER STRINGS
@@ -107,55 +222,57 @@ The following is a list of all permitted cipher strings and their meanings.
The default cipher list.
This is determined at compile time and is normally
B<ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2>.
B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>.
When used, this must be the first cipherstring specified.
默认密码列表。 这是在编译时确定的，通常是ALL：！COMPLEMENTOFDEFAULT：！eNULL。 使用时，必须是指定的第一个密码。
=item B<COMPLEMENTOFDEFAULT>
the ciphers included in B<ALL>, but not enabled by default. Currently
this is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>,
which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
The ciphers included in B<ALL>, but not enabled by default. Currently
this includes all RC4 and anonymous ciphers. Note that this rule does
not cover B<eNULL>, which is not included by B<ALL> (use B<COMPLEMENTOFALL> if
necessary). Note that RC4 based ciphersuites are not built into GmSSL by
default (see the enable-weak-ssl-ciphers option to Configure).
密码包含在ALL中，但默认情况下未启用。 目前这包括所有RC4和匿名密码。 请注意，此规则不涵盖eNULL（不包括在所有内容中）（如有必要，请使用COMPLEMENTOFALL）。 请注意，默认情况下，基于RC4的密码套件不会内置到GmSSL中（请参阅配置的enable-weak-ssl-ciphers选项）。
=item B<ALL>
all cipher suites except the B<eNULL> ciphers which must be explicitly enabled;
as of OpenSSL, the B<ALL> cipher suites are reasonably ordered by default
All cipher suites except the B<eNULL> ciphers (which must be explicitly enabled
if needed).
As of GmSSL 1.0.0, the B<ALL> cipher suites are sensibly ordered by default.
除eNULL密码之外的所有密码套件（必要时必须明确启用）。 从GmSSL 1.0.0开始，默认情况下，ALL密码套件被明确地排序。
=item B<COMPLEMENTOFALL>
the cipher suites not enabled by B<ALL>, currently being B<eNULL>.
The cipher suites not enabled by B<ALL>, currently B<eNULL>.
密码套件未被ALL启用，目前为eNULL
=item B<HIGH>
"high" encryption cipher suites. This currently means those with key lengths larger
than 128 bits, and some cipher suites with 128-bit keys.
"high" encryption cipher suites. This currently means those with key lengths
larger than 128 bits, and some cipher suites with 128-bit keys.
“高”加密密码套件。 这当前是指密钥长度大于128位的密码，
以及一些128位密钥的密码套件。
=item B<MEDIUM>
"medium" encryption cipher suites, currently some of those using 128 bit encryption.
"medium" encryption cipher suites, currently some of those using 128 bit
encryption.
“中”加密密码套件，目前有些使用128位加密。
=item B<LOW>
Low strength encryption cipher suites, currently those using 64 or 56 bit
encryption algorithms but excluding export cipher suites.
As of OpenSSL 1.0.2g, these are disabled in default builds.
"low" encryption cipher suites, currently those using 64 or 56 bit
encryption algorithms but excluding export cipher suites. All these
ciphersuites have been removed as of GmSSL 1.1.0.
=item B<EXP>, B<EXPORT>
Export strength encryption algorithms. Including 40 and 56 bits algorithms.
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXPORT40>
40-bit export encryption algorithms
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXPORT56>
56-bit export encryption algorithms. In OpenSSL 0.9.8c and later the set of
56 bit export ciphers is empty unless OpenSSL has been explicitly configured
with support for experimental ciphers.
As of OpenSSL 1.0.2g, these are disabled in default builds.
“低”加密密码套件，目前使用64或56位加密算法，但不包括导出密码套件。 所有这些密码套件已经从GmSSL 1.1.0移除。
=item B<eNULL>, B<NULL>
@@ -163,269 +280,315 @@ The "NULL" ciphers that is those offering no encryption. Because these offer no
encryption at all and are a security risk they are not enabled via either the
B<DEFAULT> or B<ALL> cipher strings.
Be careful when building cipherlists out of lower-level primitives such as
B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers.
When in doubt, include B<!eNULL> in your cipherlist.
B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers. When in
doubt, include B<!eNULL> in your cipherlist.
“NULL”密码是不提供加密功能的密码。 因为这些不提供任何加密，并且是一个安全风险，它们不能通过DEFAULT或ALL密码字符串启用。 从低级原语（如kRSA或aECDSA）构建密码列表时要小心，因为它们与eNULL密码重叠。 如有疑问，请在您的密码列表中加入！eNULL。
=item B<aNULL>
The cipher suites offering no authentication. This is currently the anonymous
DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable
to a "man in the middle" attack and so their use is normally discouraged.
to "man in the middle" attacks and so their use is discouraged.
These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL>
ciphers.
Be careful when building cipherlists out of lower-level primitives such as
B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers.
When in doubt, include B<!aNULL> in your cipherlist.
=item B<kRSA>, B<RSA>
密码套件不提供认证。 这是目前的匿名DH算法和匿名ECDH算法。 这些密码套件容易受到“中间人”攻击，所以不鼓励使用它们。 这些被排除在DEFAULT密码之外，但被包含在ALL密码中。 在使用kDHE或AES等低级原语构建密码列表时要小心，因为它们与aNULL密码重叠。 如有疑问，请在您的密码列表中加入！aNULL。
cipher suites using RSA key exchange or authentication. B<RSA> is an alias for
B<kRSA>.
=item B<kRSA>, B<aRSA>, B<RSA>
Cipher suites using RSA key exchange, authentication or either respectively.
密码套件使用RSA密钥交换，认证或分别。
=item B<kDHr>, B<kDHd>, B<kDH>
cipher suites using DH key agreement and DH certificates signed by CAs with RSA
and DSS keys or either respectively.
Cipher suites using static DH key agreement and DH certificates signed by CAs
with RSA and DSS keys or either respectively.
All these cipher suites have been removed in GmSSL 1.1.0.
=item B<kDHE>, B<kEDH>
使用静态DH密钥协议的密码套件和由CA与RSA和DSS密钥分别签署的DH证书。 所有这些密码套件已在GmSSL 1.1.0中删除。
cipher suites using ephemeral DH key agreement, including anonymous cipher
=item B<kDHE>, B<kEDH>, B<DH>
Cipher suites using ephemeral DH key agreement, including anonymous cipher
suites.
密码套件使用短暂的DH密钥协议，包括匿名密码套件。
=item B<DHE>, B<EDH>
cipher suites using authenticated ephemeral DH key agreement.
Cipher suites using authenticated ephemeral DH key agreement.
密码套件使用经认证的短时DH密钥协议。
=item B<ADH>
anonymous DH cipher suites, note that this does not include anonymous Elliptic
Anonymous DH cipher suites, note that this does not include anonymous Elliptic
Curve DH (ECDH) cipher suites.
=item B<DH>
匿名DH密码套件，请注意，这不包括匿名椭圆曲线DH（ECDH）密码套件。
cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH.
=item B<kEECDH>, B<kECDHE>, B<ECDH>
=item B<kECDHr>, B<kECDHe>, B<kECDH>
cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA
keys or either respectively.
=item B<kECDHE>, B<kEECDH>
cipher suites using ephemeral ECDH key agreement, including anonymous
Cipher suites using ephemeral ECDH key agreement, including anonymous
cipher suites.
密码套件使用短暂的ECDH密钥协议，包括匿名密码套件。
=item B<ECDHE>, B<EECDH>
cipher suites using authenticated ephemeral ECDH key agreement.
Cipher suites using authenticated ephemeral ECDH key agreement.
密码套件使用经认证的短暂ECDH密钥协议。
=item B<AECDH>
anonymous Elliptic Curve Diffie Hellman cipher suites.
Anonymous Elliptic Curve Diffie-Hellman cipher suites.
=item B<ECDH>
cipher suites using ECDH key exchange, including anonymous, ephemeral and
fixed ECDH.
=item B<aRSA>
cipher suites using RSA authentication, i.e. the certificates carry RSA keys.
匿名椭圆曲线Diffie-Hellman密码套件。
=item B<aDSS>, B<DSS>
cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
Cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
使用DSS认证的密码套件，即证书携带DSS密钥.
=item B<aDH>
cipher suites effectively using DH authentication, i.e. the certificates carry
Cipher suites effectively using DH authentication, i.e. the certificates carry
DH keys.
All these cipher suites have been removed in GmSSL 1.1.0.
=item B<aECDH>
cipher suites effectively using ECDH authentication, i.e. the certificates
carry ECDH keys.
密码套件有效地使用DH认证，即证书携带DH密钥。
所有这些密码套件已在GmSSL 1.1.0中删除。
=item B<aECDSA>, B<ECDSA>
cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
keys.
=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
使用ECDSA身份验证的密码套件，即证书包含ECDSA键。
ciphers suites using FORTEZZA key exchange, authentication, encryption or all
FORTEZZA algorithms. Not implemented.
=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3>
Lists ciphersuites which are only supported in at least TLS v1.2, TLS v1.0 or
SSL v3.0 respectively.
Note: there are no ciphersuites specific to TLS v1.1.
Since this is only the minimum version, if, for example, TLSv1.0 is negotiated
then both TLSv1.0 and SSLv3.0 ciphersuites are available.
Note: these cipher strings B<do not> change the negotiated version of SSL or
TLS, they only affect the list of available cipher suites.
=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2>
TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note:
there are no ciphersuites specific to TLS v1.1.
=item B<AES128>, B<AES256>, B<AES>
cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
密码套件使用128位AES，256位AES或128或256位AES。
=item B<AESGCM>
AES in Galois Counter Mode (GCM): these ciphersuites are only supported
in TLS v1.2.
AES在Galois计数器模式（GCM）中：这些密码器仅在TLS v1.2中支持。
=item B<AESCCM>, B<AESCCM8>
AES in Cipher Block Chaining - Message Authentication Mode (CCM): these
ciphersuites are only supported in TLS v1.2. B<AESCCM> references CCM
cipher suites using both 16 and 8 octet Integrity Check Value (ICV)
while B<AESCCM8> only references 8 octet ICV.
密码块链中的AES - 消息认证模式（CCM）：TLS v1.2中仅支持这些密码。 AESCCM参考CCM密码套件，使用16和8个字节的完整性检查值（ICV），而AESCCM8仅引用8个八位字节的ICV。
=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
CAMELLIA.
密码套件使用128位CAMELLIA，256位CAMELLIA或128或256位CAMELLIA。
=item B<CHACHA20>
cipher suites using ChaCha20.
密码套件使用ChaCha20。
=item B<3DES>
cipher suites using triple DES.
密码套件使用三重DES
=item B<DES>
cipher suites using DES (not triple DES).
Cipher suites using DES (not triple DES).
All these cipher suites have been removed in GmSSL 1.1.0.
密码套件使用DES（不是三重DES）。 所有这些密码套件已在GmSSL 1.1.0中删除。
=item B<RC4>
cipher suites using RC4.
Cipher suites using RC4.
密码套件使用RC4
=item B<RC2>
cipher suites using RC2.
Cipher suites using RC2.
密码套件使用RC2
=item B<IDEA>
cipher suites using IDEA.
Cipher suites using IDEA.
密码套件使用IDEA
=item B<SEED>
cipher suites using SEED.
Cipher suites using SEED.
密码套件使用SEED
=item B<MD5>
cipher suites using MD5.
Cipher suites using MD5.
密码套件使用MD5
=item B<SHA1>, B<SHA>
cipher suites using SHA1.
Cipher suites using SHA1.
密码套件使用SHA1
=item B<SHA256>, B<SHA384>
ciphersuites using SHA256 or SHA384.
Cipher suites using SHA256 or SHA384.
=item B<aGOST>
密码套件使用SHA256或SHA384
cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction
(needs an engine supporting GOST algorithms).
=item B<aGOST>
Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication
(needs an engine supporting GOST algorithms).
密码套件使用GOST R34.10（2001或94）用来认证
=item B<aGOST01>
cipher suites using GOST R 34.10-2001 authentication.
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)
密码套件采用GOST R 34.10-2001认证。
=item B<kGOST>
cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
Cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
密码套件，使用VKO 34.10密钥交换，在RFC 4357中规定。
=item B<GOST94>
cipher suites, using HMAC based on GOST R 34.11-94.
Cipher suites, using HMAC based on GOST R 34.11-94.
密码套件，使用基于GOST R 34.11-94的HMAC。
=item B<GOST89MAC>
cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
Cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
密码套件使用GOST 28147-89 MAC B <代替> HMAC。
=item B<PSK>
cipher suites using pre-shared keys (PSK).
All cipher suites using pre-shared keys (PSK).
所有使用预共享密钥（PSK）的密码套件。
=item B<kPSK>, B<kECDHEPSK>, B<kDHEPSK>, B<kRSAPSK>
Cipher suites using PSK key exchange, ECDHE_PSK, DHE_PSK or RSA_PSK.
密码套件使用PSK密钥交换，ECDHE_PSK，DHE_PSK或RSA_PSK。
=item B<aPSK>
Cipher suites using PSK authentication (currently all PSK modes apart from
RSA_PSK).
使用PSK认证的密码套件（目前除了所有的PSK模式
RSA_PSK）。
=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
enables suite B mode operation using 128 (permitting 192 bit mode by peer)
Enables suite B mode of operation using 128 (permitting 192 bit mode by peer)
128 bit (not permitting 192 bit by peer) or 192 bit level of security
respectively. If used these cipherstrings should appear first in the cipher
list and anything after them is ignored. Setting Suite B mode has additional
consequences required to comply with RFC6460. In particular the supported
signature algorithms is reduced to support only ECDSA and SHA256 or SHA384,
only the elliptic curves P-256 and P-384 can be used and only the two suite B
compliant ciphersuites (ECDHE-ECDSA-AES128-GCM-SHA256 and
ECDHE-ECDSA-AES256-GCM-SHA384) are permissible.
respectively.
If used these cipherstrings should appear first in the cipher
list and anything after them is ignored.
Setting Suite B mode has additional consequences required to comply with
RFC6460.
In particular the supported signature algorithms is reduced to support only
ECDSA and SHA256 or SHA384, only the elliptic curves P-256 and P-384 can be
used and only the two suite B compliant ciphersuites
(ECDHE-ECDSA-AES128-GCM-SHA256 and ECDHE-ECDSA-AES256-GCM-SHA384) are
permissible.
启用套件B的操作模式，使用128位（允许对等体的192位模式）128位（不允许192位对等）或192位级别的安全性。 如果使用这些密码应该首先出现在密码列表中，并且忽略它们之后的任何内容。 设置Suite B模式需要符合RFC6460所需的其他后果。 特别地，支持的签名算法被简化为仅支持ECDSA和SHA256或SHA384，仅可以使用椭圆曲线P-256和P-384，并且只能使用两个套件B兼容密码（ECDHE-ECDSA-AES128-GCM-SHA256和 ECDHE-ECDSA-AES256-GCM-SHA384）。
=back
=head1 CIPHER SUITE NAMES
The following lists give the SSL or TLS cipher suites names from the
relevant specification and their OpenSSL equivalents. It should be noted,
relevant specification and their GmSSL equivalents. It should be noted,
that several cipher suite names do not include the authentication used,
e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
=head2 SSL v3.0 cipher suites.
=head2 SSL v3.0 cipher suites
SSL_RSA_WITH_NULL_MD5 NULL-MD5
SSL_RSA_WITH_NULL_SHA NULL-SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5
SSL_RSA_WITH_RC4_128_MD5 RC4-MD5
SSL_RSA_WITH_RC4_128_SHA RC4-SHA
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5
SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA
SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
SSL_DH_DSS_WITH_DES_CBC_SHA DH-DSS-DES-CBC-SHA
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA
SSL_DH_RSA_WITH_DES_CBC_SHA DH-RSA-DES-CBC-SHA
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5
SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA
SSL_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented.
SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented.
SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented.
=head2 TLS v1.0 cipher suites.
=head2 TLS v1.0 cipher suites
TLS_RSA_WITH_NULL_MD5 NULL-MD5
TLS_RSA_WITH_NULL_SHA NULL-SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5
TLS_RSA_WITH_RC4_128_MD5 RC4-MD5
TLS_RSA_WITH_RC4_128_SHA RC4-SHA
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5
TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA
TLS_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_DES_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_DES_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA
TLS_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA
TLS_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5
TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA
TLS_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
=head2 AES ciphersuites from RFC3268, extending TLS v1.0
@@ -479,7 +642,7 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
=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.
algorithms, such as the B<ccgost> engine, included in the GmSSL distribution.
TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89
TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89
@@ -490,26 +653,10 @@ algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
Note: these ciphers can also be used in SSL v3.
TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DES-CBC-SHA
TLS_RSA_EXPORT1024_WITH_RC4_56_SHA EXP1024-RC4-SHA
TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA
TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA EXP1024-DHE-DSS-RC4-SHA
TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA
=head2 Elliptic curve cipher suites.
TLS_ECDH_RSA_WITH_NULL_SHA ECDH-RSA-NULL-SHA
TLS_ECDH_RSA_WITH_RC4_128_SHA ECDH-RSA-RC4-SHA
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA ECDH-RSA-DES-CBC3-SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ECDH-RSA-AES128-SHA
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA ECDH-RSA-AES256-SHA
TLS_ECDH_ECDSA_WITH_NULL_SHA ECDH-ECDSA-NULL-SHA
TLS_ECDH_ECDSA_WITH_RC4_128_SHA ECDH-ECDSA-RC4-SHA
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA ECDH-ECDSA-DES-CBC3-SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA ECDH-ECDSA-AES128-SHA
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA ECDH-ECDSA-AES256-SHA
TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA
@@ -557,16 +704,6 @@ Note: these ciphers can also be used in SSL v3.
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 ECDH-RSA-AES128-SHA256
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 ECDH-RSA-AES256-SHA384
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 ECDH-RSA-AES128-GCM-SHA256
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 ECDH-RSA-AES256-GCM-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 ECDH-ECDSA-AES128-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 ECDH-ECDSA-AES256-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 ECDH-ECDSA-AES128-GCM-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 ECDH-ECDSA-AES256-GCM-SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256
@@ -582,65 +719,170 @@ Note: these ciphers can also be used in SSL v3.
TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256
TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384
=head2 Pre shared keying (PSK) cipheruites
RSA_WITH_AES_128_CCM AES128-CCM
RSA_WITH_AES_256_CCM AES256-CCM
DHE_RSA_WITH_AES_128_CCM DHE-RSA-AES128-CCM
DHE_RSA_WITH_AES_256_CCM DHE-RSA-AES256-CCM
RSA_WITH_AES_128_CCM_8 AES128-CCM8
RSA_WITH_AES_256_CCM_8 AES256-CCM8
DHE_RSA_WITH_AES_128_CCM_8 DHE-RSA-AES128-CCM8
DHE_RSA_WITH_AES_256_CCM_8 DHE-RSA-AES256-CCM8
ECDHE_ECDSA_WITH_AES_128_CCM ECDHE-ECDSA-AES128-CCM
ECDHE_ECDSA_WITH_AES_256_CCM ECDHE-ECDSA-AES256-CCM
ECDHE_ECDSA_WITH_AES_128_CCM_8 ECDHE-ECDSA-AES128-CCM8
ECDHE_ECDSA_WITH_AES_256_CCM_8 ECDHE-ECDSA-AES256-CCM8
TLS_PSK_WITH_RC4_128_SHA PSK-RC4-SHA
TLS_PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
TLS_PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
TLS_PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
=head2 Camellia HMAC-Based ciphersuites from RFC6367, extending TLS v1.2
=head2 Deprecated SSL v2.0 cipher suites.
TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256
TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384
TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-RSA-CAMELLIA128-SHA256
TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-RSA-CAMELLIA256-SHA384
SSL_CK_RC4_128_WITH_MD5 RC4-MD5
SSL_CK_RC4_128_EXPORT40_WITH_MD5 Not implemented.
SSL_CK_RC2_128_CBC_WITH_MD5 RC2-CBC-MD5
SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 Not implemented.
SSL_CK_IDEA_128_CBC_WITH_MD5 IDEA-CBC-MD5
SSL_CK_DES_64_CBC_WITH_MD5 Not implemented.
SSL_CK_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5
=head2 Pre-shared keying (PSK) ciphersuites
PSK_WITH_NULL_SHA PSK-NULL-SHA
DHE_PSK_WITH_NULL_SHA DHE-PSK-NULL-SHA
RSA_PSK_WITH_NULL_SHA RSA-PSK-NULL-SHA
PSK_WITH_RC4_128_SHA PSK-RC4-SHA
PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
DHE_PSK_WITH_RC4_128_SHA DHE-PSK-RC4-SHA
DHE_PSK_WITH_3DES_EDE_CBC_SHA DHE-PSK-3DES-EDE-CBC-SHA
DHE_PSK_WITH_AES_128_CBC_SHA DHE-PSK-AES128-CBC-SHA
DHE_PSK_WITH_AES_256_CBC_SHA DHE-PSK-AES256-CBC-SHA
RSA_PSK_WITH_RC4_128_SHA RSA-PSK-RC4-SHA
RSA_PSK_WITH_3DES_EDE_CBC_SHA RSA-PSK-3DES-EDE-CBC-SHA
RSA_PSK_WITH_AES_128_CBC_SHA RSA-PSK-AES128-CBC-SHA
RSA_PSK_WITH_AES_256_CBC_SHA RSA-PSK-AES256-CBC-SHA
PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
DHE_PSK_WITH_AES_128_GCM_SHA256 DHE-PSK-AES128-GCM-SHA256
DHE_PSK_WITH_AES_256_GCM_SHA384 DHE-PSK-AES256-GCM-SHA384
RSA_PSK_WITH_AES_128_GCM_SHA256 RSA-PSK-AES128-GCM-SHA256
RSA_PSK_WITH_AES_256_GCM_SHA384 RSA-PSK-AES256-GCM-SHA384
PSK_WITH_AES_128_CBC_SHA256 PSK-AES128-CBC-SHA256
PSK_WITH_AES_256_CBC_SHA384 PSK-AES256-CBC-SHA384
PSK_WITH_NULL_SHA256 PSK-NULL-SHA256
PSK_WITH_NULL_SHA384 PSK-NULL-SHA384
DHE_PSK_WITH_AES_128_CBC_SHA256 DHE-PSK-AES128-CBC-SHA256
DHE_PSK_WITH_AES_256_CBC_SHA384 DHE-PSK-AES256-CBC-SHA384
DHE_PSK_WITH_NULL_SHA256 DHE-PSK-NULL-SHA256
DHE_PSK_WITH_NULL_SHA384 DHE-PSK-NULL-SHA384
RSA_PSK_WITH_AES_128_CBC_SHA256 RSA-PSK-AES128-CBC-SHA256
RSA_PSK_WITH_AES_256_CBC_SHA384 RSA-PSK-AES256-CBC-SHA384
RSA_PSK_WITH_NULL_SHA256 RSA-PSK-NULL-SHA256
RSA_PSK_WITH_NULL_SHA384 RSA-PSK-NULL-SHA384
PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
ECDHE_PSK_WITH_RC4_128_SHA ECDHE-PSK-RC4-SHA
ECDHE_PSK_WITH_3DES_EDE_CBC_SHA ECDHE-PSK-3DES-EDE-CBC-SHA
ECDHE_PSK_WITH_AES_128_CBC_SHA ECDHE-PSK-AES128-CBC-SHA
ECDHE_PSK_WITH_AES_256_CBC_SHA ECDHE-PSK-AES256-CBC-SHA
ECDHE_PSK_WITH_AES_128_CBC_SHA256 ECDHE-PSK-AES128-CBC-SHA256
ECDHE_PSK_WITH_AES_256_CBC_SHA384 ECDHE-PSK-AES256-CBC-SHA384
ECDHE_PSK_WITH_NULL_SHA ECDHE-PSK-NULL-SHA
ECDHE_PSK_WITH_NULL_SHA256 ECDHE-PSK-NULL-SHA256
ECDHE_PSK_WITH_NULL_SHA384 ECDHE-PSK-NULL-SHA384
PSK_WITH_CAMELLIA_128_CBC_SHA256 PSK-CAMELLIA128-SHA256
PSK_WITH_CAMELLIA_256_CBC_SHA384 PSK-CAMELLIA256-SHA384
DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 DHE-PSK-CAMELLIA128-SHA256
DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 DHE-PSK-CAMELLIA256-SHA384
RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 RSA-PSK-CAMELLIA128-SHA256
RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 RSA-PSK-CAMELLIA256-SHA384
ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-PSK-CAMELLIA128-SHA256
ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-PSK-CAMELLIA256-SHA384
PSK_WITH_AES_128_CCM PSK-AES128-CCM
PSK_WITH_AES_256_CCM PSK-AES256-CCM
DHE_PSK_WITH_AES_128_CCM DHE-PSK-AES128-CCM
DHE_PSK_WITH_AES_256_CCM DHE-PSK-AES256-CCM
PSK_WITH_AES_128_CCM_8 PSK-AES128-CCM8
PSK_WITH_AES_256_CCM_8 PSK-AES256-CCM8
DHE_PSK_WITH_AES_128_CCM_8 DHE-PSK-AES128-CCM8
DHE_PSK_WITH_AES_256_CCM_8 DHE-PSK-AES256-CCM8
=head2 ChaCha20-Poly1305 cipher suites, extending TLS v1.2
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-RSA-CHACHA20-POLY1305
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-ECDSA-CHACHA20-POLY1305
TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 DHE-RSA-CHACHA20-POLY1305
TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 PSK-CHACHA20-POLY1305
TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 ECDHE-PSK-CHACHA20-POLY1305
TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 DHE-PSK-CHACHA20-POLY1305
TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 RSA-PSK-CHACHA20-POLY1305
=head2 Older names used by GmSSL
The following names are accepted by older releases:
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA)
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA)
=head1 NOTES
Some compiled versions of OpenSSL may not include all the ciphers
Some compiled versions of GmSSL may not include all the ciphers
listed here because some ciphers were excluded at compile time.
=head1 EXAMPLES
Verbose listing of all OpenSSL ciphers including NULL ciphers:
Verbose listing of all GmSSL ciphers including NULL ciphers:
openssl ciphers -v 'ALL:eNULL'
gmssl ciphers -v 'ALL:eNULL'
Include all ciphers except NULL and anonymous DH then sort by
strength:
openssl ciphers -v 'ALL:!ADH:@STRENGTH'
gmssl ciphers -v 'ALL:!ADH:@STRENGTH'
Include all ciphers except ones with no encryption (eNULL) or no
authentication (aNULL):
openssl ciphers -v 'ALL:!aNULL'
gmssl ciphers -v 'ALL:!aNULL'
Include only 3DES ciphers and then place RSA ciphers last:
openssl ciphers -v '3DES:+RSA'
gmssl ciphers -v '3DES:+RSA'
Include all RC4 ciphers but leave out those without authentication:
openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
gmssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
Include all chiphers with RSA authentication but leave out ciphers without
Include all ciphers with RSA authentication but leave out ciphers without
encryption.
openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
gmssl ciphers -v 'RSA:!COMPLEMENTOFALL'
Set security level to 2 and display all ciphers consistent with level 2:
gmssl ciphers -s -v 'ALL:@SECLEVEL=2'
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)>
L<s_client(1)>, L<s_server(1)>, L<ssl(7)>
=head1 HISTORY
The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options
for cipherlist strings were added in OpenSSL 0.9.7.
The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0.
The B<-V> option for the B<ciphers> command was added in GmSSL 1.0.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

201
doc/apps/cms.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
cms - CMS utility
=head1 SYNOPSIS
B<openssl> B<cms>
B<gmssl> B<cms>
[B<-help>]
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
@@ -35,7 +38,36 @@ B<openssl> B<cms>
[B<-print>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-md digest>]
[B<-[cipher]>]
[B<-nointern>]
@@ -44,6 +76,8 @@ B<openssl> B<cms>
[B<-noattr>]
[B<-nosmimecap>]
[B<-binary>]
[B<-crlfeol>]
[B<-asciicrlf>]
[B<-nodetach>]
[B<-certfile file>]
[B<-certsout file>]
@@ -72,7 +106,7 @@ B<openssl> B<cms>
The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
verify, compress and uncompress S/MIME messages.
=head1 COMMAND OPTIONS
=head1 OPTIONS
There are fourteen operation options that set the type of operation to be
performed. The meaning of the other options varies according to the operation
@@ -80,6 +114,10 @@ type.
=over 4
=item B<-help>
Print out a usage message.
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
@@ -137,12 +175,12 @@ Verify a CMS B<DigestedData> type and output the content.
=item B<-compress>
Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib>
Create a CMS B<CompressedData> type. GmSSL must be compiled with B<zlib>
support for this option to work, otherwise it will output an error.
=item B<-uncompress>
Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be
Uncompress a CMS B<CompressedData> type and output the content. GmSSL must be
compiled with B<zlib> support for this option to work, otherwise it will
output an error.
@@ -153,13 +191,13 @@ B<EncrytedData> type and output the content.
=item B<-sign_receipt>
Generate and output a signed receipt for the supplied message. The input
Generate and output a signed receipt for the supplied message. The input
message B<must> contain a signed receipt request. Functionality is otherwise
similar to the B<-sign> operation.
=item B<-verify_receipt receipt>
Verify a signed receipt in filename B<receipt>. The input message B<must>
Verify a signed receipt in filename B<receipt>. The input message B<must>
contain the original receipt request. Functionality is otherwise similar
to the B<-verify> operation.
@@ -223,7 +261,7 @@ is S/MIME and it uses the multipart/signed MIME content type.
this option adds plain text (text/plain) MIME headers to the supplied
message if encrypting or signing. If decrypting or verifying it strips
off text headers: if the decrypted or verified message is not of MIME
off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
=item B<-noout>
@@ -248,6 +286,14 @@ B<-verify>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
@@ -257,11 +303,11 @@ default digest algorithm for the signing key will be used (usually SHA1).
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>. See L<B<enc>|enc(1)> for a list of ciphers
supported by your version of OpenSSL.
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for a list of ciphers
supported by your version of GmSSL.
If not specified triple DES is used. Only used with B<-encrypt> and
If not specified triple DES is used. Only used with B<-encrypt> and
B<-EncryptedData_create> commands.
=item B<-nointern>
@@ -300,6 +346,20 @@ effectively using CR and LF as end of line: as required by the S/MIME
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
=item B<-crlfeol>
normally the output file uses a single B<LF> as end of line. When this
option is present B<CRLF> is used instead.
=item B<-asciicrlf>
when signing use ASCII CRLF format canonicalisation. This strips trailing
whitespace from all lines, deletes trailing blank lines at EOF and sets
the encapsulated content type. This option is normally used with detached
content and an output signature format of DER. This option is not normally
needed when verifying as it is enabled automatically if the encapsulated
content format is detected.
=item B<-nodetach>
when signing a message use opaque signing: this form is more resistant
@@ -343,7 +403,7 @@ identifier extension. Supported by B<-sign> and B<-encrypt> options.
=item B<-receipt_request_all -receipt_request_first>
for B<-sign> option include a signed receipt request. Indicate requests should
be provided by all receipient or first tier recipients (those mailed directly
be provided by all recipient or first tier recipients (those mailed directly
and not from a mailing list). Ignored it B<-receipt_request_from> is included.
=item B<-receipt_request_from emailaddress>
@@ -353,7 +413,7 @@ address where receipts should be supplied.
=item B<-receipt_request_to emailaddress>
Add an explicit email address where signed receipts should be sent to. This
Add an explicit email address where signed receipts should be sent to. This
option B<must> but supplied if a signed receipt it requested.
=item B<-receipt_request_print>
@@ -365,7 +425,7 @@ requests.
specify symmetric key to use. The key must be supplied in hex format and be
consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
content encryption key using an AES key in the B<KEKRecipientInfo> type.
@@ -381,7 +441,7 @@ B<KEKRecipientInfo> structures.
set the encapsulated content type to B<type> if not supplied the B<Data> type
is used. The B<type> argument can be any valid OID name in either text or
numerical format.
numerical format.
=item B<-inkey file>
@@ -401,20 +461,20 @@ or to modify default parameters for ECDH.
=item B<-passin arg>
the private 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
one or more certificates of message recipients: used when encrypting
a message.
a message.
=item B<-to, -from, -subject>
@@ -423,10 +483,16 @@ 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 -check_ss_sig -no_alt_chains>
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
Set various certificate chain validation options. See the
L<verify(1)> manual page for details.
=back
@@ -438,7 +504,7 @@ a blank line. Piping the mail directly to sendmail is one way to
achieve the correct format.
The supplied message to be signed or encrypted must include the
necessary MIME headers or many S/MIME clients wont display it
necessary MIME headers or many S/MIME clients won't display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
@@ -459,7 +525,7 @@ The B<-resign> option uses an existing message digest when adding a new
signer. This means that attributes must be present in at least one existing
signer using the same message digest or this operation will fail.
The B<-stream> and B<-indef> options enable experimental streaming I/O support.
The B<-stream> and B<-indef> options enable streaming I/O support.
As a result the encoding is BER using indefinite length constructed encoding
and no longer DER. Streaming is supported for the B<-encrypt> operation and the
B<-sign> operation if the content is not detached.
@@ -473,10 +539,10 @@ attempt is made to locate the recipient by trying each potential recipient
in turn using the supplied private key. To thwart the MMA attack
(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
tried whether they succeed or not and if no recipients match the message
is "decrypted" using a random key which will typically output garbage.
is "decrypted" using a random key which will typically output garbage.
The B<-debug_decrypt> option can be used to disable the MMA attack protection
and return an error if no recipient can be found: this option should be used
with caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>).
with caution. For a fuller description see L<CMS_decrypt(3)>).
=head1 EXIT CODES
@@ -536,54 +602,54 @@ be processed by the older B<smime> command.
Create a cleartext signed message:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
gmssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
Create an opaque signed message
openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
gmssl cms -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
Create a signed message, include some additional certificates and
read the private key from another file:
openssl cms -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
gmssl cms -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
Create a signed message with two signers, use key identifier:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem -keyid
gmssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem -keyid
Send a signed message under Unix directly to sendmail, including headers:
openssl cms -sign -in in.txt -text -signer mycert.pem \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
gmssl cms -sign -in in.txt -text -signer mycert.pem \
-from steve@gmssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
gmssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
Send encrypted mail using triple DES:
openssl cms -encrypt -in in.txt -from steve@openssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
gmssl cms -encrypt -in in.txt -from steve@gmssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
Sign and encrypt mail:
openssl cms -sign -in ml.txt -signer my.pem -text \
| openssl cms -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
gmssl cms -sign -in ml.txt -signer my.pem -text \
| gmssl cms -encrypt -out mail.msg \
-from steve@gmssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
Decrypt mail:
openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
gmssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
The output from Netscape form signing is a PKCS#7 structure with the
detached signature format. You can use this program to verify the
@@ -593,36 +659,36 @@ it with:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command,
and using the command,
openssl cms -verify -inform PEM -in signature.pem -content content.txt
gmssl cms -verify -inform PEM -in signature.pem -content content.txt
alternatively you can base64 decode the signature and use
openssl cms -verify -inform DER -in signature.der -content content.txt
gmssl cms -verify -inform DER -in signature.der -content content.txt
Create an encrypted message using 128 bit Camellia:
openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
gmssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
Add a signer to an existing message:
openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
gmssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
Sign mail using RSA-PSS:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -keyopt rsa_padding_mode:pss
gmssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -keyopt rsa_padding_mode:pss
Create encrypted mail using RSA-OAEP:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip cert.pem -keyopt rsa_padding_mode:oaep
gmssl cms -encrypt -in plain.txt -out mail.msg \
-recip cert.pem -keyopt rsa_padding_mode:oaep
Use SHA256 KDF with an ECDH certificate:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
gmssl cms -encrypt -in plain.txt -out mail.msg \
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
=head1 BUGS
@@ -647,18 +713,27 @@ No revocation checking is done on the signer's certificate.
=head1 HISTORY
The use of multiple B<-signer> options and the B<-resign> command were first
added in OpenSSL 1.0.0
added in GmSSL 1.0.0
The B<keyopt> option was first added in OpenSSL 1.1.0
The B<keyopt> option was first added in GmSSL 1.1.0
The use of B<-recip> to specify the recipient when encrypting mail was first
added to OpenSSL 1.1.0
added to GmSSL 1.1.0
Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
Support for RSA-OAEP and RSA-PSS was first added to GmSSL 1.1.0.
The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
to OpenSSL 1.1.0.
to GmSSL 1.1.0.
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to GmSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

121
doc/apps/config.pod
View File

@@ -1,18 +1,19 @@
=pod
=for comment openssl_manual_section:5
=encoding utf8
=for comment gmssl_manual_section:5
=head1 NAME
config - OpenSSL CONF library configuration files
config - GmSSL CONF library configuration files
=head1 DESCRIPTION
The OpenSSL CONF library can be used to read configuration files.
It is used for the OpenSSL master configuration file B<openssl.cnf>
The GmSSL CONF library can be used to read configuration files.
It is used for the GmSSL master configuration file B<openssl.cnf>
and in a few other places like B<SPKAC> files and certificate extension
files for the B<x509> utility. OpenSSL applications can also use the
files for the B<x509> utility. GmSSL applications can also use the
CONF library for their own purposes.
A configuration file is divided into a number of sections. Each section
@@ -47,8 +48,7 @@ or B<${section::name}>. By using the form B<$ENV::name> environment
variables can be substituted. It is also possible to assign values to
environment variables by using the name B<ENV::name>, this will work
if the program looks up environment variables using the B<CONF> library
instead of calling B<getenv()> directly. The value string must not exceed 64k in
length after variable expansion. Otherwise an error will occur.
instead of calling getenv() directly.
It is possible to escape certain characters by using any kind of quote
or the B<\> character. By making the last character of a line a B<\>
@@ -57,27 +57,27 @@ the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
=head1 OPENSSL LIBRARY CONFIGURATION
In OpenSSL 0.9.7 and later applications can automatically configure certain
aspects of OpenSSL using the master OpenSSL configuration file, or optionally
an alternative configuration file. The B<openssl> utility includes this
functionality: any sub command uses the master OpenSSL configuration file
Applications can automatically configure certain
aspects of GmSSL using the master GmSSL configuration file, or optionally
an alternative configuration file. The B<gmssl> utility includes this
functionality: any sub command uses the master GmSSL configuration file
unless an option is used in the sub command to use an alternative configuration
file.
To enable library configuration the default section needs to contain an
To enable library configuration the default section needs to contain an
appropriate line which points to the main configuration section. The default
name is B<openssl_conf> which is used by the B<openssl> utility. Other
name is B<gmssl_conf> which is used by the B<gmssl> utility. Other
applications may use an alternative name such as B<myapplicaton_conf>.
The configuration section should consist of a set of name value pairs which
contain specific module configuration information. The B<name> represents
the name of the I<configuration module> the meaning of the B<value> is
the name of the I<configuration module> the meaning of the B<value> is
module specific: it may, for example, represent a further configuration
section containing configuration module specific information. E.g.
openssl_conf = openssl_init
gmssl_conf = gmssl_init
[openssl_init]
[gmssl_init]
oid_section = new_oids
engines = engine_section
@@ -92,27 +92,27 @@ section containing configuration module specific information. E.g.
The features of each configuration module are described below.
=head2 ASN1 OBJECT CONFIGURATION MODULE
=head2 ASN1 Object Configuration Module
This module has the name B<oid_section>. The value of this variable points
to a section containing name value pairs of OIDs: the name is the OID short
and long name, the value is the numerical form of the OID. Although some of
the B<openssl> utility sub commands already have their own ASN1 OBJECT section
the B<gmssl> utility sub commands already have their own ASN1 OBJECT section
functionality not all do. By using the ASN1 OBJECT configuration module
B<all> the B<openssl> utility sub commands can see the new objects as well
B<all> the B<gmssl> utility sub commands can see the new objects as well
as any compliant applications. For example:
[new_oids]
some_new_oid = 1.2.3.4
some_other_oid = 1.2.3.5
In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
It is also possible to set the value to the long name followed
by a comma and the numerical OID form. For example:
shortName = some object long name, 1.2.3.4
=head2 ENGINE CONFIGURATION MODULE
=head2 Engine Configuration Module
This ENGINE configuration module has the name B<engines>. The value of this
variable points to a section containing further ENGINE configuration
@@ -142,7 +142,7 @@ For example:
[bar_section]
... "bar" ENGINE specific commands ...
The command B<engine_id> is used to give the ENGINE name. If used this
The command B<engine_id> is used to give the ENGINE name. If used this
command must be first. For example:
[engine_section]
@@ -166,10 +166,10 @@ then an attempt will be made to initialize the ENGINE after all commands in
its section have been processed.
The command B<default_algorithms> sets the default algorithms an ENGINE will
supply using the functions B<ENGINE_set_default_string()>
supply using the functions ENGINE_set_default_string().
If the name matches none of the above command names it is assumed to be a
ctrl command which is sent to the ENGINE. The value of the command is the
ctrl command which is sent to the ENGINE. The value of the command is the
argument to the ctrl command. If the value is the string B<EMPTY> then no
value is sent to the command.
@@ -191,7 +191,7 @@ For example:
# Supply all default algorithms
default_algorithms = ALL
=head2 EVP CONFIGURATION MODULE
=head2 EVP Configuration Module
This modules has the name B<alg_section> which points to a section containing
algorithm commands.
@@ -209,13 +209,41 @@ For example:
fips_mode = on
=head2 SSL Configuration Module
This module has the name B<ssl_conf> which points to a section containing
SSL configurations.
Each line in the SSL configuration section contains the name of the
configuration and the section containing it.
Each configuration section consists of command value pairs for B<SSL_CONF>.
Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls
SSL_CTX_config() or SSL_config() with the appropriate configuration name.
Note: any characters before an initial dot in the configuration section are
ignored so the same command can be used multiple times.
For example:
ssl_conf = ssl_sect
[ssl_sect]
server = server_section
[server_section]
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem
Ciphers = ALL:!RC4
=head1 NOTES
If a configuration file attempts to expand a variable that doesn't exist
then an error is flagged and the file will not load. This can happen
if an attempt is made to expand an environment variable that doesn't
exist. For example in a previous version of OpenSSL the default OpenSSL
exist. For example in a previous version of GmSSL the default GmSSL
master configuration file used the value of B<HOME> which may not be
defined on non Unix systems and would cause an error.
@@ -239,7 +267,7 @@ Here is a sample configuration file using some of the features
mentioned above.
# This is the default section.
HOME=/temp
RANDFILE= ${ENV::HOME}/.rnd
configdir=$ENV::HOME/config
@@ -265,11 +293,11 @@ This next example shows how to expand environment variables safely.
Suppose you want a variable called B<tmpfile> to refer to a
temporary filename. The directory it is placed in can determined by
the the B<TEMP> or B<TMP> environment variables but they may not be
the B<TEMP> or B<TMP> environment variables but they may not be
set to any value at all. If you just include the environment variable
names and the variable doesn't exist then this will cause an error when
an attempt is made to load the configuration file. By making use of the
default section both values can be looked up with B<TEMP> taking
default section both values can be looked up with B<TEMP> taking
priority and B</tmp> used if neither is defined:
TMP=/tmp
@@ -278,13 +306,13 @@ priority and B</tmp> used if neither is defined:
# The above value is used if TEMP isn't in the environment
tmpfile=${ENV::TEMP}/tmp.filename
Simple OpenSSL library configuration example to enter FIPS mode:
Simple GmSSL library configuration example to enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
gmssl_conf = gmssl_conf_section
[openssl_conf_section]
[gmssl_conf_section]
# Configuration module list
alg_section = evp_sect
@@ -293,15 +321,15 @@ Simple OpenSSL library configuration example to enter FIPS mode:
fips_mode = yes
Note: in the above example you will get an error in non FIPS capable versions
of OpenSSL.
of GmSSL.
More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
More complex GmSSL library configuration. Add OID and don't enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
gmssl_conf = gmssl_conf_section
[openssl_conf_section]
[gmssl_conf_section]
# Configuration module list
alg_section = evp_sect
oid_section = new_oids
@@ -317,13 +345,13 @@ More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
# New OID shortname and long name
newoid2 = New OID 2 long name, 1.2.3.4.2
The above examples can be used with with any application supporting library
configuration if "openssl_conf" is modified to match the appropriate "appname".
The above examples can be used with any application supporting library
configuration if "gmssl_conf" is modified to match the appropriate "appname".
For example if the second sample file above is saved to "example.cnf" then
the command line:
OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
OPENSSL_CONF=example.cnf gmssl asn1parse -genstr OID:1.2.3.4.1
will output:
@@ -346,6 +374,15 @@ file.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
L<x509(1)>, L<req(1)>, L<ca(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

64
doc/apps/crl.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
crl - CRL utility
=head1 SYNOPSIS
B<openssl> B<crl>
B<gmssl> B<crl>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-text>]
@@ -25,71 +28,105 @@ B<openssl> B<crl>
The B<crl> command processes CRL files in DER or PEM format.
=head1 COMMAND OPTIONS
crl命令以DER或PEM格式处理CRL文件。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
输出使用信息。
=item B<-inform DER|PEM>
This specifies the input format. B<DER> format is DER encoded CRL
structure. B<PEM> (the default) is a base64 encoded version of
the DER form with header and footer lines.
输入文件的格式。DER是DER编码的CRL对象。PEM（默认的格式）是base64编码的CRL对象。
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
指定文件的输出格式。跟-inform的意思一样。
=item B<-in filename>
This specifies the input filename to read from or standard input if this
option is not specified.
指定的输入文件名，一般为标注输入
=item B<-out filename>
specifies the output filename to write to or standard output by
default.
指定的输出文件名，一般为标准输出
=item B<-text>
print out the CRL in text form.
以文本的格式来打印出CRL
=item B<-nameopt option>
option which determines how the subject or issuer names are displayed. See
the description of B<-nameopt> in L<x509(1)|x509(1)>.
the description of B<-nameopt> in L<x509(1)>.
决定了名称的显示方式。
=item B<-noout>
don't output the encoded version of the CRL.
不输出CRL文件内容
=item B<-hash>
output a hash of the issuer name. This can be use to lookup CRLs in
a directory by issuer name.
输出颁发者信息的哈希值。这一项可用于在文件中根据颁发者的哈希值来查询CRL。
=item B<-hash_old>
outputs the "hash" of the CRL issuer name using the older algorithm
as used by OpenSSL versions before 1.0.0.
as used by GmSSL versions before 1.0.0.
输出CRL颁发者信息的哈希值用GmSSL1.0.0版本以前更加古老的算法。
=item B<-issuer>
output the issuer name.
输出发行者的信息。
=item B<-lastupdate>
output the lastUpdate field.
输出上一次更新的时间。
=item B<-nextupdate>
output the nextUpdate field.
输出下一次更新的时间。
=item B<-CAfile file>
verify the signature on a CRL by looking up the issuing certificate in
B<file>
指定文件来验证该CRL对象是否合法。
=item B<-CApath dir>
verify the signature on a CRL by looking up the issuing certificate in
@@ -97,6 +134,8 @@ B<dir>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
通过查找dir中的颁发证书来验证CRL上的签名。 此目录必须是标准证书目录：这是每个主题名称的哈希（使用x509 -hash）应链接到每个证书。
=back
=head1 NOTES
@@ -110,11 +149,11 @@ The PEM CRL format uses the header and footer lines:
Convert a CRL file from PEM to DER:
openssl crl -in crl.pem -outform DER -out crl.der
gmssl crl -in crl.pem -outform DER -out crl.der
Output the text form of a DER encoded certificate:
openssl crl -in crl.der -text -noout
gmssl crl -in crl.der -text -noout
=head1 BUGS
@@ -123,6 +162,15 @@ and files too.
=head1 SEE ALSO
L<crl2pkcs7(1)|crl2pkcs7(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>
L<crl2pkcs7(1)>, L<ca(1)>, L<x509(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

30
doc/apps/crl2pkcs7.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates.
crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates
=head1 SYNOPSIS
B<openssl> B<crl2pkcs7>
B<gmssl> B<crl2pkcs7>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -20,10 +23,14 @@ The B<crl2pkcs7> command takes an optional CRL and one or more
certificates and converts them into a PKCS#7 degenerate "certificates
only" structure.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the CRL input format. B<DER> format is DER encoded CRL
@@ -64,13 +71,13 @@ included in the output file and a CRL is not read from the input file.
Create a PKCS#7 structure from a certificate and CRL:
openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem
gmssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem
Creates a PKCS#7 structure in DER format with no CRL from several
different certificates:
openssl crl2pkcs7 -nocrl -certfile newcert.pem
-certfile demoCA/cacert.pem -outform DER -out p7.der
gmssl crl2pkcs7 -nocrl -certfile newcert.pem
-certfile demoCA/cacert.pem -outform DER -out p7.der
=head1 NOTES
@@ -86,6 +93,15 @@ install user certificates and CAs in MSIE using the Xenroll control.
=head1 SEE ALSO
L<pkcs7(1)|pkcs7(1)>
L<pkcs7(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

152
doc/apps/dgst.pod
View File

@@ -1,19 +1,21 @@
=pod
=encoding utf8
=head1 NAME
dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests
dgst, sha, sha1, mdc2, ripemd160, sha224, sm3, sha384, sha512, md4, md5, blake2b, blake2s - message digests
=head1 SYNOPSIS
B<openssl> B<dgst>
[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>]
B<gmssl> B<dgst>
[B<-help>]
[B<-I<digest>>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
[B<-r>]
[B<-non-fips-allow>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
@@ -22,11 +24,12 @@ B<openssl> B<dgst>
[B<-prverify filename>]
[B<-signature filename>]
[B<-hmac key>]
[B<-non-fips-allow>]
[B<-fips-fingerprint>]
[B<-engine id>]
[B<-engine_impl>]
[B<file...>]
B<openssl>
B<gmssl>
[I<digest>]
[B<...>]
@@ -36,85 +39,126 @@ The digest functions output the message digest of a supplied file or files
in hexadecimal. The digest functions also generate and verify digital
signatures using message digests.
The generic name, B<dgst>, may be used with an option specifying the
algorithm to be used.
The default digest is I<sm3>.
A supported I<digest> name may also be used as the command name.
To see the list of supported algorithms, use the I<list --digest-commands>
command.
摘要功能输出所提供文件的消息摘要或是十六进制文件。摘要功能还能使用消息摘要生成和验证数字签名。
通用名称dgst可以与指定要使用算法的选项一起使用。默认的摘要是sm3.支持的digest名称也可作为命令名称。要查看支持的算法列表，请使用list --digest-commands。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
输出使用信息。
=item B<-I<digest>>
Specifies name of a supported digest to be used. To see the list of
supported digests, use the command I<list --digest-commands>.
指定要使用支持摘要的名称。要查看支持的摘要列表，使用命令list --digest-commands。
=item B<-c>
print out the digest in two digit groups separated by colons, only relevant if
B<hex> format output is used.
打印两个数组中的摘要的时候用冒号来分隔开。仅仅设置了hex格式输出时有效。
=item B<-d>
print out BIO debugging information.
打印出BIO调试信息值。
=item B<-hex>
digest is to be output as a hex dump. This is the default case for a "normal"
digest as opposed to a digital signature. See NOTES below for digital
signatures using B<-hex>.
摘要将作为十六进制转储输出。 这是“正常”摘要的默认情况，而不是数字签名。 请参阅下面的注释使用-hex的数字签名。
=item B<-binary>
output the digest or signature in binary form.
以二进制的形式来显示摘要结果值。
=item B<-r>
output the digest in the "coreutils" format used by programs like B<sha1sum>.
=item B<-non-fips-allow>
Allow use of non FIPS digest when in FIPS mode. This has no effect when not in
FIPS mode.
用coreutils格式来输出摘要值，被一些像shalsum的程序使用。
=item B<-out filename>
filename to output to, or standard output by default.
输出对象文件名，默认为标准输出。
=item B<-sign filename>
digitally sign the digest using the private key in "filename".
用filename中的私钥文件对数据进行签名。
=item B<-keyform arg>
Specifies the key format to sign digest with. The DER, PEM, P12,
and ENGINE formats are supported.
=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.
指定了签署摘要的密钥格式。该命令中仅仅支持DER，PEM，P12以及ENGINE格式。
=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>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
私钥密码源。
=item B<-verify filename>
verify the signature using the the public key in "filename".
verify the signature using the public key in "filename".
The output is either "Verification OK" or "Verification Failure".
使用filename中的公钥验证签名。
输出要么是验证通过要么是验证失败。
=item B<-prverify filename>
verify the signature using the the private key in "filename".
verify the signature using the private key in "filename".
使用filename中的公钥验证签名。
=item B<-signature filename>
the actual signature to verify.
实际要验证的签名
=item B<-hmac key>
create a hashed MAC using "key".
用key创建哈希MAC
=item B<-mac alg>
create MAC (keyed Message Authentication Code). The most popular MAC
@@ -123,70 +167,101 @@ 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.
创建MAC（密钥消息认证码）。 最流行的MAC算法是HMAC（基于散列的MAC），但是还有其他MAC算法不是基于哈希的，比如gost-mac算法，由ccgost引擎支持。 应通过-macopt参数设置MAC密钥和其他选项。
=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>:
通过命令到MAC算法，由-mac指定。
=over 8
=item B<key:string>
Specifies MAC key as alphnumeric string (use if key contain printable
Specifies MAC key as alphanumeric 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.
指定MAC密钥值作为字母字符串。字符串长度必须符合摘要算法的限制条件，例如对gost-mac来说是32字节。
=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.
指定MAC密钥值作为十六进制字符串。字符串长度必须符合摘要算法的限制条件，例如对gost-mac来说是32字节。
=back
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
all others.
=item B<-non-fips-allow>
enable use of non-FIPS algorithms such as MD5 even in FIPS mode.
产生随机数种子的文件
=item B<-fips-fingerprint>
compute HMAC using a specific key
for certain OpenSSL-FIPS operations.
for certain GmSSL-FIPS operations.
用指定的密钥计算HMAC，为了有关的GMSSL-FIPS操作。
=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 or B<-engine_impl> is also
specified.
使用引擎ID进行操作（包括私钥存储）。 此引擎不用作摘要算法的源，除非在配置文件中也指定了引擎，还指定了-engine_impl。
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine B<id> for digest operations.
当与-engine选项一起使用时，它还指定还使用引擎ID进行摘要操作。
=item B<file...>
file or files to digest. If no files are specified then standard input is
used.
要摘要的文件。如果没有指定文件，就使用标准输入。
=back
=head1 EXAMPLES
To create a hex-encoded message digest of a file:
openssl dgst -md5 -hex file.txt
gmssl dgst -md5 -hex file.txt
To sign a file using SHA-256 with binary file output:
openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt
gmssl dgst -sm3 -sign privatekey.pem -out signature.sign file.txt
To verify a signature:
openssl dgst -sha256 -verify publickey.pem \
gmssl dgst -sm3 -verify publickey.pem \
-signature signature.sign \
file.txt
=head1 NOTES
The digest of choice for all new applications is SHA1. Other digests are
however still widely used.
The digest mechanisms that are available will depend on the options
used when building GmSSL.
The B<list digest-commands> command can be used to list them.
New or agile applications should use probably use SHA-256. Other digests,
particularly SHA-1 and MD5, are still widely used for interoperating
with existing formats and protocols.
When signing a file, B<dgst> will automatically determine the algorithm
(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
@@ -200,9 +275,22 @@ particular ECDSA and DSA.
The signing and verify options should only be used if a single file is
being signed or verified.
Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r"
Hex signatures cannot be verified using B<gmssl>. Instead, use "xxd -r"
or similar program to transform the hex signature into a binary signature
prior to verification.
=head1 HISTORY
The default digest was changed from MD5 to SM3 in GmSSL 2.0
The FIPS-related options were removed in GmSSL 2.0
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

40
doc/apps/dhparam.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
dhparam - DH parameter manipulation and generation
=head1 SYNOPSIS
B<openssl dhparam>
B<gmssl dhparam>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in> I<filename>]
@@ -30,6 +33,10 @@ This command is used to manipulate DH parameter files.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -39,7 +46,7 @@ additional header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in> I<filename>
@@ -67,7 +74,8 @@ avoid small-subgroup attacks that may be possible otherwise.
=item B<-check>
check if the parameters are valid primes and generator.
Performs numerous checks to see if the supplied parameters are valid and
displays a warning if not.
=item B<-2>, B<-5>
@@ -79,8 +87,8 @@ default generator 2.
=item B<-rand> I<file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -103,7 +111,7 @@ this option prints out the DH parameters in human readable form.
=item B<-C>
this option converts the parameters into C code. The parameters can then
be loaded by calling the B<get_dh>I<numbits>B<()> function.
be loaded by calling the get_dhNNNN() function.
=item B<-engine id>
@@ -117,9 +125,9 @@ for all available algorithms.
=head1 WARNINGS
The program B<dhparam> combines the functionality of the programs B<dh> and
B<gendh> in previous versions of OpenSSL and SSLeay. The B<dh> and B<gendh>
programs are retained for now but may have different purposes in future
versions of OpenSSL.
B<gendh> in previous versions of GmSSL. The B<dh> and B<gendh>
programs are retained for now but may have different purposes in future
versions of GmSSL.
=head1 NOTES
@@ -128,7 +136,7 @@ PEM format DH parameters use the header and footer lines:
-----BEGIN DH PARAMETERS-----
-----END DH PARAMETERS-----
OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42
GmSSL currently only supports the older PKCS#3 DH, not the newer X9.42
DH.
This program manipulates DH parameters not keys.
@@ -139,11 +147,15 @@ There should be a way to generate and manipulate DH keys.
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>
L<dsaparam(1)>
=head1 HISTORY
=head1 COPYRIGHT
The B<dhparam> command was added in OpenSSL 0.9.5.
The B<-dsaparam> option was added in OpenSSL 0.9.6.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

42
doc/apps/dsa.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
dsa - DSA key processing
=head1 SYNOPSIS
B<openssl> B<dsa>
B<gmssl> B<dsa>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -36,10 +39,14 @@ forms and their components printed out. B<Note> This command uses the
traditional SSLeay compatible format for private key encryption: newer
applications should use the more secure PKCS#8 format using the B<pkcs8>
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option with a private key uses
@@ -54,7 +61,7 @@ PKCS#8 format is also accepted.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -66,7 +73,7 @@ prompted for.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-out filename>
@@ -78,7 +85,7 @@ filename.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
@@ -138,27 +145,36 @@ The PEM public key format uses the header and footer lines:
To remove the pass phrase on a DSA private key:
openssl dsa -in key.pem -out keyout.pem
gmssl dsa -in key.pem -out keyout.pem
To encrypt a private key using triple DES:
openssl dsa -in key.pem -des3 -out keyout.pem
gmssl dsa -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
To convert a private key from PEM to DER format:
openssl dsa -in key.pem -outform DER -out keyout.der
gmssl dsa -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl dsa -in key.pem -text -noout
gmssl dsa -in key.pem -text -noout
To just output the public part of a private key:
openssl dsa -in key.pem -pubout -out pubkey.pem
gmssl dsa -in key.pem -pubout -out pubkey.pem
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>, L<gendsa(1)|gendsa(1)>, L<rsa(1)|rsa(1)>,
L<genrsa(1)|genrsa(1)>
L<dsaparam(1)>, L<gendsa(1)>, L<rsa(1)>,
L<genrsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

30
doc/apps/dsaparam.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
dsaparam - DSA parameter manipulation and generation
=head1 SYNOPSIS
B<openssl dsaparam>
B<gmssl dsaparam>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in filename>]
@@ -27,6 +30,10 @@ This command is used to manipulate or generate DSA parameter files.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -36,7 +43,7 @@ of the B<DER> format base64 encoded with additional header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -62,7 +69,7 @@ this option prints out the DSA parameters in human readable form.
=item B<-C>
this option converts the parameters into C code. The parameters can then
be loaded by calling the B<get_dsaXXX()> function.
be loaded by calling the get_dsaXXX() function.
=item B<-genkey>
@@ -72,8 +79,8 @@ parameters.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -104,7 +111,16 @@ DSA parameters is often used to generate several distinct keys.
=head1 SEE ALSO
L<gendsa(1)|gendsa(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
L<rsa(1)|rsa(1)>
L<gendsa(1)>, L<dsa(1)>, L<genrsa(1)>,
L<rsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

112
doc/apps/ec.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
ec - EC key processing
=head1 SYNOPSIS
B<openssl> B<ec>
B<gmssl> B<ec>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -15,7 +18,7 @@ B<openssl> B<ec>
[B<-passout arg>]
[B<-des>]
[B<-des3>]
[B<-idea>]
[B<-sms4>]
[B<-text>]
[B<-noout>]
[B<-param_out>]
@@ -23,20 +26,30 @@ B<openssl> B<ec>
[B<-pubout>]
[B<-conv_form arg>]
[B<-param_enc arg>]
[B<-no_public>]
[B<-check>]
[B<-engine id>]
=head1 DESCRIPTION
The B<ec> command processes EC keys. They can be converted between various
forms and their components printed out. B<Note> OpenSSL uses the
forms and their components printed out. B<Note> GmSSL uses the
private key format specified in 'SEC 1: Elliptic Curve Cryptography'
(http://www.secg.org/). To convert a OpenSSL EC private key into the
(http://www.secg.org/). To convert an GmSSL EC private key into the
PKCS#8 private key format use the B<pkcs8> command.
=head1 COMMAND OPTIONS
ec命令处理EC密钥。 它们可以在各种形式之间进行转换，并将其组件打印出来。 注意GmSSL使用“SEC 1：椭圆曲线加密”（http://www.secg.org/）中指定的私钥格式。 要将GmSSL EC私钥转换为PKCS＃8私钥格式，请使用pkcs8命令。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
输出使用信息。
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option with a private key uses
@@ -46,21 +59,29 @@ The B<PEM> form is the default format: it consists of the B<DER> format base64
encoded with additional header and footer lines. In the case of a private key
PKCS#8 format is also accepted.
该指令指出了输入文件格式。DER选项是一个私钥，它用ASN.1 DER编码的SEC1私钥文件。当为公钥时，用RFC3280指定的SubjectPublicKeyInfo结构。默认的是PEM格式，它也接受PKCS#8格式的私钥。
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
该指令指出了输出格式。与-inform指令意义相同。
=item B<-in filename>
This specifies the input filename to read a key from or standard input if this
option is not specified. If the key is encrypted a pass phrase will be
prompted for.
如果未指定此选项，则指定从或从标准输入读取密钥的输入文件名。 如果密钥加密，将提示输入密码。
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
指定私钥包含口令存放方式。
=item B<-out filename>
@@ -69,15 +90,19 @@ is not specified. If any encryption options are set then a pass phrase will be
prompted for. The output filename should B<not> be the same as the input
filename.
这指定了未指定要写入或输出的标准输出的输出文件名。 如果设置了任何加密选项，则会提示输入密码。 输出文件名不能与输入文件名相同。
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-des|-des3|-idea>
输出文件口令保护存放方式。
These options encrypt the private key with the DES, triple DES, IDEA or
any other cipher supported by OpenSSL before outputting it. A pass phrase is
=item B<-des|-des3|-sms4>
These options encrypt the private key with the DES, triple DES, SMS4 or
any other cipher supported by GmSSL before outputting it. A pass phrase is
prompted for.
If none of these options is specified the key is written in plain text. This
means that using the B<ec> utility to read in an encrypted key with no
@@ -85,29 +110,41 @@ encryption option can be used to remove the pass phrase from a key, or by
setting the encryption options it can be use to add or change the pass phrase.
These options can only be used with PEM format output files.
这些选项在输出之前，使用DES，三重DES，SMS4或GmSSL支持的任何其他密码加密私钥。 提示通行短语。 如果没有指定这些选项，则键将以纯文本形式写入。 这意味着使用ec实用程序读取加密密钥，无加密选项可用于从密钥中删除密码短语，或通过设置可用于添加或更改密码短语的加密选项。 这些选项只能用于PEM格式的输出文件。
=item B<-text>
prints out the public, private key components and parameters.
输出公钥和私钥的组成参数。
=item B<-noout>
this option prevents output of the encoded version of the key.
不输出密钥信息。
=item B<-modulus>
this option prints out the value of the public key component of the key.
该选项输出公钥组件值。
=item B<-pubin>
by default a private key is read from the input file: with this option a
public key is read instead.
默认读取为私钥，输入该指令后，从输入文件中读取公钥。
=item B<-pubout>
by default a private key is output. With this option a public
key will be output instead. This option is automatically set if the input is
a public key.
输入该指令后，公钥值到输出文件中。默认保存私钥到输出文件。如果输入是公钥该选项将自动设置。
=item B<-conv_form>
This specifies how the points on the elliptic curve are converted
@@ -118,15 +155,31 @@ B<Note> Due to patent issues the B<compressed> option is disabled
by default for binary curves and can be enabled by defining
the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
这指定椭圆曲线上的点如何转换为八位字节串。 可能的值有：压缩（默认值），未压缩和混合。 有关点转换表单的更多信息，请阅读X9.62标准。 注意由于专利问题，压缩选项默认情况下禁用二进制曲线，并且可以通过在编译时定义预处理器宏OPENSSL_EC_BIN_PT_COMP来启用。
=item B<-param_enc arg>
This specifies how the elliptic curve parameters are encoded.
Possible value are: B<named_curve>, i.e. the ec parameters are
specified by a OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
specified by an OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
EC parameters structures). The default value is B<named_curve>.
B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
is currently not implemented in OpenSSL.
B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
is currently not implemented in GmSSL.
这指定椭圆曲线参数的编码方式。 可能的值为：named_curve，即ec参数由OID指定，或显式指定ec参数（参见RFC 3279以了解EC参数结构的定义）。 默认值为named_curve。 注意，如RFC 3279所述，implicitlyCA替代方案目前尚未在GmSSL中实现
=item B<-no_public>
This option omits the public key components from the private key output.
该指令省略了私钥输出中的公钥组件。
=item B<-check>
this option checks the consistency of an EC private or public key.
该指令检查了EC私钥或公钥的一致性。
=item B<-engine id>
@@ -135,6 +188,8 @@ 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.
指定引擎。
=back
=head1 NOTES
@@ -153,38 +208,39 @@ The PEM public key format uses the header and footer lines:
To encrypt a private key using triple DES:
openssl ec -in key.pem -des3 -out keyout.pem
gmssl ec -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
To convert a private key from PEM to DER format:
openssl ec -in key.pem -outform DER -out keyout.der
gmssl ec -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl ec -in key.pem -text -noout
gmssl ec -in key.pem -text -noout
To just output the public part of a private key:
openssl ec -in key.pem -pubout -out pubkey.pem
gmssl ec -in key.pem -pubout -out pubkey.pem
To change the parameters encoding to B<explicit>:
openssl ec -in key.pem -param_enc explicit -out keyout.pem
gmssl ec -in key.pem -param_enc explicit -out keyout.pem
To change the point conversion form to B<compressed>:
openssl ec -in key.pem -conv_form compressed -out keyout.pem
gmssl ec -in key.pem -conv_form compressed -out keyout.pem
=head1 SEE ALSO
L<ecparam(1)|ecparam(1)>, L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>
L<ecparam(1)>, L<dsa(1)>, L<rsa(1)>
=head1 HISTORY
=head1 COPYRIGHT
The ec command was first introduced in OpenSSL 0.9.8.
Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org).
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

94
doc/apps/ecparam.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
ecparam - EC parameter manipulation and generation
=head1 SYNOPSIS
B<openssl ecparam>
B<gmssl ecparam>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in filename>]
@@ -28,60 +31,88 @@ B<openssl ecparam>
This command is used to manipulate or generate EC parameter files.
此命令用于操作或生成EC参数文件。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
输出使用信息。
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN.1 DER encoded
form compatible with RFC 3279 EcpkParameters. The PEM form is the default
format: it consists of the B<DER> format base64 encoded with additional
format: it consists of the B<DER> format base64 encoded with additional
header and footer lines.
输入文件格式，DER或PEM格式。DER采用与RFC 3279EcpkParameters兼容的ASN1的DER标准格式。PEM格式是默认格式：它由DER格式base64编码，带有附加的页眉和页脚行。
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
指出输出格式。和-inform用法相同。
=item B<-in filename>
This specifies the input filename to read parameters from or standard input if
this option is not specified.
指出输入的如果未指定此选项，则指定从或从标准输入读取参数的输入文件名。
=item B<-out filename>
This specifies the output filename parameters to. Standard output is used
if this option is not present. The output filename should B<not> be the same
as the input filename.
指定输出文件名参数。 如果此选项不存在，则使用标准输出。 输出文件名不能与输入文件名相同
=item B<-noout>
This option inhibits the output of the encoded version of the parameters.
不打印参数编码的版本信息。
=item B<-text>
This option prints out the EC parameters in human readable form.
打印椭圆曲线密钥参数信息值。
=item B<-C>
This option converts the EC parameters into C code. The parameters can then
be loaded by calling the B<get_ec_group_XXX()> function.
be loaded by calling the get_ec_group_XXX() function.
用C语言打印椭圆曲线参数。然后可以通过调用get_ec_group_XXX函数来加载参数。
=item B<-check>
Validate the elliptic curve parameters.
验证椭圆曲线密钥参数。
=item B<-name arg>
Use the EC parameters with the specified 'short' name. Use B<-list_curves>
to get a list of all currently implemented EC parameters.
使用EC参数的指定短名称。使用-list_curves来得到所有当前实现的EC参数的列表。
=item B<-list_curves>
If this options is specified B<ecparam> will print out a list of all
currently implemented EC parameters names and exit.
打印所有可用的短名称。
=item B<-conv_form>
This specifies how the points on the elliptic curve are converted
@@ -92,33 +123,43 @@ B<Note> Due to patent issues the B<compressed> option is disabled
by default for binary curves and can be enabled by defining
the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
这指定椭圆曲线上的点如何转换为八位字节串。 可能的值有：压缩（默认值），未压缩和混合。 有关点转换表单的更多信息，请阅读X9.62标准。 注意由于专利问题，压缩选项默认情况下禁用二进制曲线，并且可以通过在编译时定义预处理器宏OPENSSL_EC_BIN_PT_COMP来启用。
=item B<-param_enc arg>
This specifies how the elliptic curve parameters are encoded.
Possible value are: B<named_curve>, i.e. the ec parameters are
specified by a OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
specified by an OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
EC parameters structures). The default value is B<named_curve>.
B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
is currently not implemented in OpenSSL.
B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
is currently not implemented in GmSSL.
这指定椭圆曲线参数的编码方式。 可能的值为：named_curve，即ec参数由OID指定，或显式指定ec参数（参见RFC 3279以了解EC参数结构的定义）。 默认值为named_curve。 注意，如RFC 3279所述，implicitlyCA替代方案目前尚未在GmSSL中实现
=item B<-no_seed>
This option inhibits that the 'seed' for the parameter generation
is included in the ECParameters structure (see RFC 3279).
该选项禁止参数生成“seed”包含在ECParameters结构中（参见RFC 3279）。
=item B<-genkey>
This option will generate a EC private key using the specified parameters.
This option will generate an EC private key using the specified parameters.
该指令会生成一个指定参数的EC私钥。
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
含有随机数产生种子的文件。
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<ecparam>
@@ -126,6 +167,8 @@ 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.
指定硬件引擎。该引擎会被设为所有可行的算法的默认引擎。
=back
=head1 NOTES
@@ -135,45 +178,46 @@ PEM format EC parameters use the header and footer lines:
-----BEGIN EC PARAMETERS-----
-----END EC PARAMETERS-----
OpenSSL is currently not able to generate new groups and therefore
B<ecparam> can only create EC parameters from known (named) curves.
GmSSL is currently not able to generate new groups and therefore
B<ecparam> can only create EC parameters from known (named) curves.
=head1 EXAMPLES
To create EC parameters with the group 'prime192v1':
openssl ecparam -out ec_param.pem -name prime192v1
gmssl ecparam -out ec_param.pem -name prime192v1
To create EC parameters with explicit parameters:
openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit
gmssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit
To validate given EC parameters:
openssl ecparam -in ec_param.pem -check
gmssl ecparam -in ec_param.pem -check
To create EC parameters and a private key:
openssl ecparam -out ec_key.pem -name prime192v1 -genkey
gmssl ecparam -out ec_key.pem -name prime192v1 -genkey
To change the point encoding to 'compressed':
openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed
gmssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed
To print out the EC parameters to standard output:
openssl ecparam -in ec_param.pem -noout -text
gmssl ecparam -in ec_param.pem -noout -text
=head1 SEE ALSO
L<ec(1)|ec(1)>, L<dsaparam(1)|dsaparam(1)>
L<ec(1)>, L<dsaparam(1)>
=head1 HISTORY
=head1 COPYRIGHT
The ecparam command was first introduced in OpenSSL 0.9.8.
Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org)
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

155
doc/apps/enc.pod
View File

@@ -1,12 +1,16 @@
=pod
=encoding utf8
=head1 NAME
enc - symmetric cipher routines
=head1 SYNOPSIS
B<openssl enc -ciphername>
B<gmssl enc -ciphername>
[B<-help>]
[B<-ciphers>]
[B<-in filename>]
[B<-out filename>]
[B<-pass arg>]
@@ -22,7 +26,7 @@ B<openssl enc -ciphername>
[B<-salt>]
[B<-nosalt>]
[B<-z>]
[B<-md>]
[B<-md digest>]
[B<-p>]
[B<-P>]
[B<-bufsize number>]
@@ -38,79 +42,118 @@ using various block and stream ciphers using keys based on passwords
or explicitly provided. Base64 encoding or decoding can also be performed
either by itself or in addition to the encryption or decryption.
对称密码命令允许使用基于密码或明确提供的密钥的各种块和流密码来加密或解密数据。 Base64编码或解码也可以通过本身或加密或解密来执行。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
输出使用信息
=item B<-ciphers>
List all supported ciphers.
列出所有支持的密码。
=item B<-in filename>
the input filename, standard input by default.
输入的文件名，默认为标准输入。
=item B<-out filename>
the output filename, standard output by default.
输出的文件名，默认为标准输出。
=item B<-pass arg>
the password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-salt>
use a salt in the key derivation routines. This is the default.
=item B<-nosalt>
don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
used except for test purposes or compatibility with ancient versions of OpenSSL
and SSLeay.
指定密码的来源。
=item B<-e>
encrypt the input data: this is the default.
进行加密操作，默认操作。
=item B<-d>
decrypt the input data.
进行解密操作。
=item B<-a>
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.
base64处理数据。这意味着加密结果进行64位编码。解密前先进行base64解码。
=item B<-base64>
same as B<-a>
和-a一样。
=item B<-A>
if the B<-a> option is set then base64 process the data on one line.
将生成的结果在文件中只有一行。
=item B<-k password>
the password to derive the key from. This is for compatibility with previous
versions of OpenSSL. Superseded by the B<-pass> argument.
versions of GmSSL. Superseded by the B<-pass> argument.
加密口令。这是为了当前GmSSL版本的兼容。
=item B<-kfile filename>
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
This is for compatibility with previous versions of GmSSL. Superseded by
the B<-pass> argument.
指定口令存放的文件。
=item B<-md digest>
Use the specified digest to create the key from the passphrase.
The default algorithm is SM3.
运用指定摘要算法来从密码中创建密钥。默认算法为SM3.
=item B<-nosalt>
do not use a salt
don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
used except for test purposes or compatibility with ancient versions of
GmSSL.
在密钥导出例程中不使用salt，除了测试目的或与以前版本的Gmssl兼容，不应使用此选项。
=item B<-salt>
use salt (randomly generated or provide with B<-S> option) when
encrypting (this is the default).
在加密过程中使用salt（默认设置）。
=item B<-S salt>
the actual salt to use: this must be represented as a string of hex digits.
salt的值为16进制。
=item B<-K key>
the actual key to use: this must be represented as a string comprised only
@@ -120,6 +163,10 @@ key given with the B<-K> option will be used and the IV generated from the
password will be taken. It probably does not make much sense to specify
both key and password.
用的实际密钥值：这个必须提出，它是一个16进制的输入口令。如果没有这个选
项IV必须用-IV选项指定。当key和密钥都指定时，用-K选项给定的key将会被使
用，而使用密钥来产生初始化向量IV。不建议两者都指定。
=item B<-iv IV>
the actual IV to use: this must be represented as a string comprised only
@@ -127,51 +174,70 @@ of hex digits. When only the key is specified using the B<-K> option, the
IV must explicitly be defined. When a password is being specified using
one of the other options, the IV is generated from this password.
实际上使用的初始化向量：这个必须提出，它是一个16进制的输入口令。如果没有这个选
项IV必须用-IV选项指定。当一个密钥用其中一个选项所指定，IV将会与偶这个口令
值来产生。
=item B<-p>
print out the key and IV used.
打印使用的密钥和IV。
=item B<-P>
print out the key and IV used then immediately exit: don't do any encryption
or decryption.
打印使用的key和IV然后直接退出，不做加密和解密操作。
=item B<-bufsize number>
set the buffer size for I/O
设置I/O操作的缓冲区大小。
=item B<-nopad>
disable standard block padding
没有数据填充。
=item B<-debug>
debug the BIOs used for I/O.
调试用于I/O的BIO。
=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
decryption. This option exists only if GmSSL with compiled with zlib
or zlib-dynamic option.
在加密或解密之后使用zlib压缩或解压缩明文。 只有使用zlib或zlib-
dynamic选项编译的GmSSL时，此选项才会存在。
=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>. But the first form doesn't work with
The program can be called either as B<gmssl ciphername> or
B<gmssl 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
options can only be used for hardware-assisted implementations of
ciphers, which are supported by GmSSL core or other engine, specified
in the configuration file.
When enc command lists supported ciphers, ciphers provided by engines,
@@ -181,7 +247,7 @@ A password will be prompted for to derive the key and IV if necessary.
The B<-salt> option should B<ALWAYS> be used if the key is being derived
from a password unless you want compatibility with previous versions of
OpenSSL and SSLeay.
GmSSL.
Without the B<-salt> option it is possible to perform efficient dictionary
attacks on the password and to attack stream cipher encrypted data. The reason
@@ -211,8 +277,8 @@ Blowfish and RC5 algorithms use a 128 bit key.
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
unsupported options (for example B<gmssl enc -help>) includes a
list of ciphers, supported by your version of GmSSL, including
ones provided by configured engines.
The B<enc> program does not support authenticated encryption modes
@@ -255,7 +321,7 @@ authentication tag.
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)
gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
idea-cbc IDEA algorithm in CBC mode
idea same as idea-cbc
@@ -281,44 +347,44 @@ authentication tag.
rc5-ecb RC5 cipher in ECB mode
rc5-ofb RC5 cipher in OFB mode
aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode
aes-[128|192|256] Alias for aes-[128|192|256]-cbc
aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode
aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode
aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode
aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode
aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode
aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode
aes[128|192|256] Alias for aes-[128|192|256]-cbc
aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode
aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode
aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode
aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode
aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode
=head1 EXAMPLES
Just base64 encode a binary file:
openssl base64 -in file.bin -out file.b64
gmssl base64 -in file.bin -out file.b64
Decode the same file
openssl base64 -d -in file.b64 -out file.bin
gmssl base64 -d -in file.b64 -out file.bin
Encrypt a file using triple DES in CBC mode using a prompted password:
openssl des3 -salt -in file.txt -out file.des3
gmssl des3 -salt -in file.txt -out file.des3
Decrypt a file using a supplied password:
openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
gmssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
Encrypt a file then base64 encode it (so it can be sent via mail for example)
using Blowfish in CBC mode:
openssl bf -a -salt -in file.txt -out file.bf
gmssl bf -a -salt -in file.txt -out file.bf
Base64 decode a file then decrypt it:
openssl bf -d -salt -a -in file.bf -out file.txt
gmssl bf -d -salt -a -in file.bf -out file.txt
Decrypt some data using a supplied 40 bit RC4 key:
openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
gmssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
=head1 BUGS
@@ -330,4 +396,17 @@ The B<enc> program only supports a fixed number of algorithms with
certain parameters. So if, for example, you want to use RC2 with a
76 bit key or RC4 with an 84 bit key you can't use this program.
=head1 HISTORY
The default digest was changed from MD5 to SHA256 in Openssl 1.1.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

24
doc/apps/errstr.pod
View File

@@ -1,20 +1,26 @@
=pod
=encoding utf8
=head1 NAME
errstr - lookup error codes
=head1 SYNOPSIS
B<openssl errstr error_code>
B<gmssl errstr error_code>
=head1 DESCRIPTION
Sometimes an application will not load error message and only
numerical forms will be available. The B<errstr> utility can be used to
numerical forms will be available. The B<errstr> utility can be used to
display the meaning of the hex code. The hex code is the hex digits after the
second colon.
=head1 OPTIONS
None.
=head1 EXAMPLE
The error code:
@@ -22,18 +28,20 @@ The error code:
27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
can be displayed with:
openssl errstr 2006D080
gmssl errstr 2006D080
to produce the error message:
error:2006D080:BIO routines:BIO_new_file:no such file
=head1 SEE ALSO
=head1 COPYRIGHT
L<err(3)|err(3)>,
L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/apps/gendsa.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
gendsa - generate a DSA private key from a set of parameters
=head1 SYNOPSIS
B<openssl> B<gendsa>
B<gmssl> B<gendsa>
[B<-help>]
[B<-out filename>]
[B<-aes128>]
[B<-aes192>]
@@ -24,12 +27,21 @@ B<openssl> B<gendsa>
=head1 DESCRIPTION
The B<gendsa> command generates a DSA private key from a DSA parameter file
(which will be typically generated by the B<openssl dsaparam> command).
(which will be typically generated by the B<gmssl dsaparam> command).
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
Output the key to the specified file. If this argument is not specified then
standard output is used.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with specified
@@ -39,8 +51,8 @@ If none of these options is specified no encryption is used.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -55,7 +67,7 @@ for all available algorithms.
This option specifies the DSA parameter file to use. The parameters in this
file determine the size of the private key. DSA parameters can be generated
and examined using the B<openssl dsaparam> command.
and examined using the B<gmssl dsaparam> command.
=back
@@ -66,7 +78,16 @@ much quicker that RSA key generation for example.
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
L<rsa(1)|rsa(1)>
L<dsaparam(1)>, L<dsa(1)>, L<genrsa(1)>,
L<rsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

97
doc/apps/genpkey.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
genpkey - generate a private key
=head1 SYNOPSIS
B<openssl> B<genpkey>
B<gmssl> B<genpkey>
[B<-help>]
[B<-out filename>]
[B<-outform PEM|DER>]
[B<-pass arg>]
@@ -26,10 +29,14 @@ The B<genpkey> command generates a private key.
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
the output filename. If this argument is not specified then standard output is
used.
Output the key to the specified file. If this argument is not specified then
standard output is used.
=item B<-outform DER|PEM>
@@ -38,7 +45,7 @@ This specifies the output format DER or PEM.
=item B<-pass arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-cipher>
@@ -68,14 +75,14 @@ implementation. See B<KEY GENERATION OPTIONS> below for more details.
=item B<-genparam>
generate a set of parameters instead of a private key. If used this option must
precede and B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
precede any B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
=item B<-paramfile filename>
Some public key algorithms generate a private key based on a set of parameters.
They can be supplied using this option. If this option is used the public key
algorithm used is determined by the parameters. If used this option must
precede and B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
are mutually exclusive.
=item B<-text>
@@ -87,8 +94,8 @@ parameters along with the PEM or DER structure.
=head1 KEY GENERATION OPTIONS
The options supported by each algorith and indeed each implementation of an
algorithm can vary. The options for the OpenSSL implementations are detailed
The options supported by each algorithm and indeed each implementation of an
algorithm can vary. The options for the GmSSL implementations are detailed
below.
=head1 RSA KEY GENERATION OPTIONS
@@ -141,19 +148,28 @@ and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
=head1 EC PARAMETER GENERATION OPTIONS
The EC parameter generation options below can also
be supplied as EC key generation options. This can (for example) generate a
key from a named curve without the need to use an explicit parameter file.
=over 4
=item B<ec_paramgen_curve:curve>
the EC curve to use.
the EC curve to use. GmSSL supports NIST curve names such as "P-256".
=item B<ec_param_enc:encoding>
the encoding to use for parameters. The "encoding" parameter must be either
"named_curve" or "explicit".
=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
one should load the ccgost engine in the GmSSL configuration file.
See README.gost file in the engines/ccgost directory of the source
distribution for more details.
Use of a parameter file for the GOST R 34.10 algorithm is optional.
@@ -178,6 +194,9 @@ numeric OID. Following parameter sets are supported:
=back
=head1 X25519 KEY GENERATION OPTIONS
The X25519 algorithm does not currently support any key generation options.
=head1 NOTES
@@ -190,39 +209,71 @@ can be used.
Generate an RSA private key using default parameters:
openssl genpkey -algorithm RSA -out key.pem
gmssl genpkey -algorithm RSA -out key.pem
Encrypt output private key using 128 bit AES and the passphrase "hello":
openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
gmssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
Generate a 2048 bit RSA key using 3 as the public exponent:
openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \
-pkeyopt rsa_keygen_pubexp:3
gmssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \
-pkeyopt rsa_keygen_pubexp:3
Generate 1024 bit DSA parameters:
openssl genpkey -genparam -algorithm DSA -out dsap.pem \
-pkeyopt dsa_paramgen_bits:1024
gmssl genpkey -genparam -algorithm DSA -out dsap.pem \
-pkeyopt dsa_paramgen_bits:1024
Generate DSA key from parameters:
openssl genpkey -paramfile dsap.pem -out dsakey.pem
gmssl genpkey -paramfile dsap.pem -out dsakey.pem
Generate 1024 bit DH parameters:
openssl genpkey -genparam -algorithm DH -out dhp.pem \
-pkeyopt dh_paramgen_prime_len:1024
gmssl genpkey -genparam -algorithm DH -out dhp.pem \
-pkeyopt dh_paramgen_prime_len:1024
Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
gmssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
Generate DH key from parameters:
openssl genpkey -paramfile dhp.pem -out dhkey.pem
gmssl genpkey -paramfile dhp.pem -out dhkey.pem
Generate EC parameters:
gmssl genpkey -genparam -algorithm EC -out ecp.pem \
-pkeyopt ec_paramgen_curve:secp384r1 \
-pkeyopt ec_param_enc:named_curve
Generate EC key from parameters:
gmssl genpkey -paramfile ecp.pem -out eckey.pem
Generate EC key directly:
gmssl genpkey -algorithm EC -out eckey.pem \
-pkeyopt ec_paramgen_curve:P-384 \
-pkeyopt ec_param_enc:named_curve
Generate an X25519 private key:
gmssl genpkey -algorithm X25519 -out xkey.pem
=head1 HISTORY
The ability to use NIST curve names, and to generate an EC key directly,
were added in GmSSL 1.0.2.
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/apps/genrsa.pod
View File

@@ -1,21 +1,20 @@
=pod
=encoding utf8
=head1 NAME
genrsa - generate an RSA private key
=head1 SYNOPSIS
B<openssl> B<genrsa>
B<gmssl> B<genrsa>
[B<-help>]
[B<-out filename>]
[B<-passout arg>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-aria128>]
[B<-aria192>]
[B<-aria256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
@@ -48,9 +47,9 @@ standard output is used.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-aes128|-aes192|-aes256|-aria128|-aria192|-aria256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with specified
cipher before outputting it. If none of these options is
@@ -79,7 +78,7 @@ for all available algorithms.
=item B<numbits>
the size of the private key to generate in bits. This must be the last option
specified. The default is 2048.
specified. The default is 512.
=back
@@ -108,9 +107,9 @@ L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

26
doc/apps/nseq.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
nseq - create or examine a netscape certificate sequence
nseq - create or examine a Netscape certificate sequence
=head1 SYNOPSIS
B<openssl> B<nseq>
B<gmssl> B<nseq>
[B<-help>]
[B<-in filename>]
[B<-out filename>]
[B<-toseq>]
@@ -18,10 +21,14 @@ sequence and prints out the certificates contained in it or takes a
file of certificates and converts it into a Netscape certificate
sequence.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read or standard input if this
@@ -44,11 +51,11 @@ a file of certificates.
Output the certificates in a Netscape certificate sequence
openssl nseq -in nseq.pem -out certs.pem
gmssl nseq -in nseq.pem -out certs.pem
Create a Netscape certificate sequence
openssl nseq -in certs.pem -toseq -out nseq.pem
gmssl nseq -in certs.pem -toseq -out nseq.pem
=head1 NOTES
@@ -67,4 +74,13 @@ It is used by Netscape certificate server for example.
This program needs a few more options: like allowing DER or PEM input and
output files and allowing multiple certificate files to be used.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

165
doc/apps/ocsp.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
ocsp - Online Certificate Status Protocol utility
=head1 SYNOPSIS
B<openssl> B<ocsp>
B<gmssl> B<ocsp>
[B<-help>]
[B<-out file>]
[B<-issuer file>]
[B<-cert file>]
@@ -25,12 +28,41 @@ B<openssl> B<ocsp>
[B<-nonce>]
[B<-no_nonce>]
[B<-url URL>]
[B<-host host:n>]
[B<-header name value>]
[B<-host host:port>]
[B<-header>]
[B<-path>]
[B<-CApath dir>]
[B<-CAfile file>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-VAfile file>]
[B<-validity_period n>]
[B<-status_age n>]
@@ -65,10 +97,19 @@ The B<ocsp> command performs many common OCSP tasks. It can be used
to print out requests and responses, create requests and send queries
to an OCSP responder and behave like a mini OCSP server itself.
=head1 OCSP CLIENT OPTIONS
=head1 OPTIONS
This command operates as either a client or a server.
The options are described below, divided into those two modes.
=head2 OCSP Client Options
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
specify output filename, default is standard output.
@@ -107,7 +148,7 @@ Additional certificates to include in the signed request.
=item B<-nonce>, B<-no_nonce>
Add an OCSP nonce extension to a request or disable OCSP nonce addition.
Normally if an OCSP request is input using the B<respin> option no
Normally if an OCSP request is input using the B<reqin> option no
nonce is added: using the B<nonce> option will force addition of a nonce.
If an OCSP request is being created (using B<cert> and B<serial> options)
a nonce is automatically added specifying B<no_nonce> overrides this.
@@ -134,15 +175,14 @@ specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
if the B<host> option is present then the OCSP request is sent to the host
B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
or "/" by default.
or "/" by default. This is equivalent to specifying B<-url> with scheme
http:// and the given hostname, port, and pathname.
=item B<-header name value>
=item B<-header name=value>
If sending a request to an OCSP server, then the specified header name and
value are added to the HTTP request. Note that the B<name> and B<value> must
be specified as two separate parameters, not as a single quoted string, and
that the header name does not have the trailing colon.
Some OCSP responders require a Host header; use this flag to provide it.
Adds the header B<name> with the specified B<value> to the OCSP request
that is sent to the responder.
This may be repeated.
=item B<-timeout seconds>
@@ -153,9 +193,24 @@ connection timeout to the OCSP responder in seconds
file or pathname containing trusted CA certificates. These are used to verify
the signature on the OCSP response.
=item B<-no_alt_chains>
=item B<-no-CAfile>
See L<B<verify>|verify(1)> manual page for details.
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set different certificate verification options.
See L<verify(1)> manual page for details.
=item B<-verify_other file>
@@ -218,26 +273,29 @@ only be used for testing purposes.
=item B<-validity_period nsec>, B<-status_age age>
these options specify the range of times, in seconds, which will be tolerated
in an OCSP response. Each certificate status response includes a B<notBefore> time and
an optional B<notAfter> time. The current time should fall between these two values, but
the interval between the two times may be only a few seconds. In practice the OCSP
responder and clients clocks may not be precisely synchronised and so such a check
may fail. To avoid this the B<-validity_period> option can be used to specify an
acceptable error range in seconds, the default value is 5 minutes.
in an OCSP response. Each certificate status response includes a B<notBefore>
time and an optional B<notAfter> time. The current time should fall between
these two values, but the interval between the two times may be only a few
seconds. In practice the OCSP responder and clients clocks may not be precisely
synchronised and so such a check may fail. To avoid this the
B<-validity_period> option can be used to specify an acceptable error range in
seconds, the default value is 5 minutes.
If the B<notAfter> time is omitted from a response then this means that new status
information is immediately available. In this case the age of the B<notBefore> field
is checked to see it is not older than B<age> seconds old. By default this additional
check is not performed.
If the B<notAfter> time is omitted from a response then this means that new
status information is immediately available. In this case the age of the
B<notBefore> field is checked to see it is not older than B<age> seconds old.
By default this additional check is not performed.
=item B<-md5|-sha1|-sha256|-ripemod160|...>
=item B<-[digest]>
this option sets digest algorithm to use for certificate identification
in the OCSP request. By default SHA-1 is used.
this option sets digest algorithm to use for certificate identification in the
OCSP request. Any digest supported by the GmSSL B<dgst> command can be used.
The default is SHA-1. This option may be used multiple times to specify the
digest used by subsequent certificate identifiers.
=back
=head1 OCSP SERVER OPTIONS
=head2 OCSP Server Options
=over 4
@@ -249,7 +307,7 @@ information.
If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise
it is in client mode. The request(s) the responder processes can be either specified on
the command line (using B<issuer> and B<serial> options), supplied in a file (using the
B<respin> option) or via external OCSP clients (if B<port> or B<url> is specified).
B<reqin> option) or via external OCSP clients (if B<port> or B<url> is specified).
If the B<index> option is present then the B<CA> and B<rsigner> options must also be
present.
@@ -286,13 +344,13 @@ option.
=item B<-nrequest number>
The OCSP server will exit after receiving B<number> requests, default unlimited.
The OCSP server will exit after receiving B<number> requests, default unlimited.
=item B<-nmin minutes>, B<-ndays days>
Number of minutes or days when fresh revocation information is available: used in the
B<nextUpdate> field. If neither option is present then the B<nextUpdate> field is
omitted meaning fresh revocation information is immediately available.
B<nextUpdate> field. If neither option is present then the B<nextUpdate> field
is omitted meaning fresh revocation information is immediately available.
=back
@@ -306,7 +364,7 @@ the OCSP request checked using the responder certificate's public key.
Then a normal certificate verify is performed on the OCSP responder certificate
building up a certificate chain in the process. The locations of the trusted
certificates used to build the chain can be specified by the B<CAfile>
and B<CApath> options or they will be looked for in the standard OpenSSL
and B<CApath> options or they will be looked for in the standard GmSSL
certificates directory.
If the initial verify fails then the OCSP verify process halts with an
@@ -334,7 +392,7 @@ If the OCSP responder is a "global responder" which can give details about
multiple CAs and has its own separate certificate chain then its root
CA can be trusted for OCSP signing. For example:
openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
gmssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
Alternatively the responder certificate itself can be explicitly trusted
with the B<-VAfile> option.
@@ -354,48 +412,57 @@ format of revocation is also inefficient for large quantities of revocation
data.
It is possible to run the B<ocsp> application in responder mode via a CGI
script using the B<respin> and B<respout> options.
script using the B<reqin> and B<respout> options.
=head1 EXAMPLES
Create an OCSP request and write it to a file:
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
gmssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
response to a file and print it out in text form
Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
response to a file, print it out in text form, and verify the response:
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
gmssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
-url http://ocsp.myhost.com/ -resp_text -respout resp.der
Read in an OCSP response and print out text form:
openssl ocsp -respin resp.der -text
gmssl ocsp -respin resp.der -text -noverify
OCSP server on port 8888 using a standard B<ca> configuration, and a separate
responder certificate. All requests and responses are printed to a file.
openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
-text -out log.txt
gmssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
-text -out log.txt
As above but exit after processing one request:
openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
gmssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
-nrequest 1
Query status information using internally generated request:
Query status information using an internally generated request:
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
gmssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
-issuer demoCA/cacert.pem -serial 1
Query status information using request read from a file, write response to a
second file.
Query status information using request read from a file, and write the response
to a second file.
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
gmssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
-reqin req.der -respout resp.der
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to GmSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

422
doc/apps/openssl.pod
View File

@@ -1,422 +0,0 @@
=pod
=head1 NAME
openssl - OpenSSL command line tool
=head1 SYNOPSIS
B<openssl>
I<command>
[ I<command_opts> ]
[ I<command_args> ]
B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> | B<list-cipher-algorithms> | B<list-message-digest-algorithms> | B<list-public-key-algorithms>]
B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
=head1 DESCRIPTION
OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL
v2/v3) and Transport Layer Security (TLS v1) network protocols and related
cryptography standards required by them.
The B<openssl> program is a command line tool for using the various
cryptography functions of OpenSSL's B<crypto> library from the shell.
It can be used for
o Creation and management of private keys, public keys and parameters
o Public key cryptographic operations
o Creation of X.509 certificates, CSRs and CRLs
o Calculation of Message Digests
o Encryption and Decryption with Ciphers
o SSL/TLS Client and Server Tests
o Handling of S/MIME signed or encrypted mail
o Time Stamp requests, generation and verification
=head1 COMMAND SUMMARY
The B<openssl> program provides a rich variety of commands (I<command> in the
SYNOPSIS above), each of which often has a wealth of options and arguments
(I<command_opts> and I<command_args> in the SYNOPSIS).
The pseudo-commands B<list-standard-commands>, B<list-message-digest-commands>,
and B<list-cipher-commands> output a list (one entry per line) of the names
of all standard commands, message digest commands, or cipher commands,
respectively, that are available in the present B<openssl> utility.
The pseudo-commands B<list-cipher-algorithms> and
B<list-message-digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
from => to
The pseudo-command B<list-public-key-algorithms> lists all supported public
key algorithms.
The pseudo-command B<no->I<XXX> tests whether a command of the
specified name is available. If no command named I<XXX> exists, it
returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1
and prints I<XXX>. In both cases, the output goes to B<stdout> and
nothing is printed to B<stderr>. Additional command line arguments
are always ignored. Since for each cipher there is a command of the
same name, this provides an easy way for shell scripts to test for the
availability of ciphers in the B<openssl> program. (B<no->I<XXX> is
not able to detect pseudo-commands such as B<quit>,
B<list->I<...>B<-commands>, or B<no->I<XXX> itself.)
=head2 STANDARD COMMANDS
=over 10
=item L<B<asn1parse>|asn1parse(1)>
Parse an ASN.1 sequence.
=item L<B<ca>|ca(1)>
Certificate Authority (CA) Management.
=item L<B<ciphers>|ciphers(1)>
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.
=item L<B<crl2pkcs7>|crl2pkcs7(1)>
CRL to PKCS#7 Conversion.
=item L<B<dgst>|dgst(1)>
Message Digest Calculation.
=item B<dh>
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.
=item L<B<dsaparam>|dsaparam(1)>
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 B<gendh>
Generation of Diffie-Hellman Parameters.
Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<gendsa>|gendsa(1)>
Generation of DSA Private Key from Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>
=item L<B<genpkey>|genpkey(1)>
Generation of Private Key or Parameters.
=item L<B<genrsa>|genrsa(1)>
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.
=item L<B<passwd>|passwd(1)>
Generation of hashed passwords.
=item L<B<pkcs12>|pkcs12(1)>
PKCS#12 Data Management.
=item L<B<pkcs7>|pkcs7(1)>
PKCS#7 Data Management.
=item L<B<pkey>|pkey(1)>
Public and private key management.
=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.
=item L<B<req>|req(1)>
PKCS#10 X.509 Certificate Signing Request (CSR) Management.
=item L<B<rsa>|rsa(1)>
RSA key management.
=item L<B<rsautl>|rsautl(1)>
RSA utility for signing, verification, encryption, and decryption. Superseded
by L<B<pkeyutl>|pkeyutl(1)>
=item L<B<s_client>|s_client(1)>
This implements a generic SSL/TLS client which can establish a transparent
connection to a remote server speaking SSL/TLS. It's intended for testing
purposes only and provides only rudimentary interface functionality but
internally uses mostly all functionality of the OpenSSL B<ssl> library.
=item L<B<s_server>|s_server(1)>
This implements a generic SSL/TLS server which accepts connections from remote
clients speaking SSL/TLS. It's intended for testing purposes only and provides
only rudimentary interface functionality but internally uses mostly all
functionality of the OpenSSL B<ssl> library. It provides both an own command
line oriented protocol for testing SSL functions and a simple HTTP response
facility to emulate an SSL/TLS-aware webserver.
=item L<B<s_time>|s_time(1)>
SSL Connection Timer.
=item L<B<sess_id>|sess_id(1)>
SSL Session Data Management.
=item L<B<smime>|smime(1)>
S/MIME mail processing.
=item L<B<speed>|speed(1)>
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)
=item L<B<verify>|verify(1)>
X.509 Certificate Verification.
=item L<B<version>|version(1)>
OpenSSL Version Information.
=item L<B<x509>|x509(1)>
X.509 Certificate Data Management.
=back
=head2 MESSAGE DIGEST COMMANDS
=over 10
=item B<md2>
MD2 Digest
=item B<md5>
MD5 Digest
=item B<mdc2>
MDC2 Digest
=item B<rmd160>
RMD-160 Digest
=item B<sha>
SHA Digest
=item B<sha1>
SHA-1 Digest
=item B<sha224>
SHA-224 Digest
=item B<sha256>
SHA-256 Digest
=item B<sha384>
SHA-384 Digest
=item B<sha512>
SHA-512 Digest
=back
=head2 ENCODING AND CIPHER COMMANDS
=over 10
=item B<base64>
Base64 Encoding
=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb>
Blowfish Cipher
=item B<cast cast-cbc>
CAST Cipher
=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb>
CAST5 Cipher
=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb>
DES Cipher
=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb>
Triple-DES Cipher
=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb>
IDEA Cipher
=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb>
RC2 Cipher
=item B<rc4>
RC4 Cipher
=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb>
RC5 Cipher
=back
=head1 PASS PHRASE ARGUMENTS
Several commands accept password arguments, typically using B<-passin>
and B<-passout> for input and output passwords respectively. These allow
the password to be obtained from a variety of sources. Both of these
options take a single argument whose format is described below. If no
password argument is given and a password is required then the user is
prompted to enter one: this will typically be read from the current
terminal with echoing turned off.
=over 10
=item B<pass:password>
the actual password is B<password>. Since the password is visible
to utilities (like 'ps' under Unix) this form should only be used
where security is not important.
=item B<env:var>
obtain the password from the environment variable B<var>. Since
the environment of other processes is visible on certain platforms
(e.g. ps under certain Unix OSes) this option should be used with caution.
=item B<file:pathname>
the first line of B<pathname> is the password. If the same B<pathname>
argument is supplied to B<-passin> and B<-passout> arguments then the first
line will be used for the input password and the next line for the output
password. B<pathname> need not refer to a regular file: it could for example
refer to a device or named pipe.
=item B<fd:number>
read the password from the file descriptor B<number>. This can be used to
send the data via a pipe for example.
=item B<stdin>
read the password from standard input.
=back
=head1 SEE ALSO
L<asn1parse(1)|asn1parse(1)>, L<ca(1)|ca(1)>, L<config(5)|config(5)>,
L<crl(1)|crl(1)>, L<crl2pkcs7(1)|crl2pkcs7(1)>, L<dgst(1)|dgst(1)>,
L<dhparam(1)|dhparam(1)>, L<dsa(1)|dsa(1)>, L<dsaparam(1)|dsaparam(1)>,
L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, L<genpkey(1)|genpkey(1)>,
L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>,
L<passwd(1)|passwd(1)>,
L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>,
L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>,
L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>,
L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>,
L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>,
L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>,
L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)>, L<x509v3_config(5)|x509v3_config(5)>
=head1 HISTORY
The openssl(1) document appeared in OpenSSL 0.9.2.
The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3;
The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0;
the B<no->I<XXX> pseudo-commands were added in OpenSSL 0.9.5a.
For notes on the availability of other commands, see their individual
manual pages.
=cut

24
doc/apps/passwd.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
passwd - compute password hashes
=head1 SYNOPSIS
B<openssl passwd>
B<gmssl passwd>
[B<-help>]
[B<-crypt>]
[B<-1>]
[B<-apr1>]
@@ -31,6 +34,10 @@ algorithm B<1> and its Apache variant B<apr1> are available.
=over 4
=item B<-help>
Print out a usage message.
=item B<-crypt>
Use the B<crypt> algorithm (default).
@@ -73,10 +80,19 @@ to each password hash.
=head1 EXAMPLES
B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>.
B<gmssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>.
B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>.
B<gmssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>.
B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
B<gmssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

94
doc/apps/pkcs12.pod
View File

@@ -1,13 +1,15 @@
=pod
=encoding utf8
=head1 NAME
pkcs12 - PKCS#12 file utility
=head1 SYNOPSIS
B<openssl> B<pkcs12>
B<gmssl> B<pkcs12>
[B<-help>]
[B<-export>]
[B<-chain>]
[B<-inkey filename>]
@@ -39,6 +41,8 @@ B<openssl> B<pkcs12>
[B<-rand file(s)>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-CSP name>]
=head1 DESCRIPTION
@@ -47,7 +51,7 @@ The B<pkcs12> command allows PKCS#12 files (sometimes referred to as
PFX files) to be created and parsed. PKCS#12 files are used by several
programs including Netscape, MSIE and MS Outlook.
=head1 COMMAND OPTIONS
=head1 OPTIONS
There are a lot of options the meaning of some depends of whether a PKCS#12 file
is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12
@@ -57,6 +61,10 @@ file can be created by using the B<-export> option (see below).
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies filename of the PKCS#12 file to be parsed. Standard input is used
@@ -71,13 +79,13 @@ default. They are all written in PEM format.
the PKCS#12 file (i.e. input file) password source. For more information about
the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
L<gmssl(1)>.
=item B<-passout arg>
pass phrase source to encrypt any outputted private keys with. For more
information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section
in L<openssl(1)|openssl(1)>.
in L<gmssl(1)>.
=item B<-password arg>
@@ -192,13 +200,13 @@ displays them.
the PKCS#12 file (i.e. output file) password source. For more information about
the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
L<gmssl(1)>.
=item B<-passin password>
pass phrase source to decrypt any input private keys with. For more information
about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
L<gmssl(1)>.
=item B<-chain>
@@ -266,8 +274,8 @@ don't attempt to provide the MAC integrity.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -281,6 +289,14 @@ CA storage as a directory. This directory must be a standard certificate
directory: that is a hash of each subject name (using B<x509 -hash>) should be
linked to each certificate.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-CSP name>
write B<name> as a Microsoft CSP name.
@@ -311,58 +327,54 @@ encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can
be used to reduce the private key encryption to 40 bit RC2. A complete
description of all algorithms is contained in the B<pkcs8> manual page.
Prior 1.1 release passwords containing non-ASCII characters were encoded
in non-compliant manner, which limited interoperability, in first hand
with Windows. But switching to standard-compliant password encoding
poses problem accessing old data protected with broken encoding. For
this reason even legacy encodings is attempted when reading the
data. If you use PKCS#12 files in production application you are advised
to convert the data, because implemented heuristic approach is not
MT-safe, its sole goal is to facilitate the data upgrade with this
utility.
=head1 EXAMPLES
Parse a PKCS#12 file and output it to a file:
openssl pkcs12 -in file.p12 -out file.pem
gmssl pkcs12 -in file.p12 -out file.pem
Output only client certificates to a file:
openssl pkcs12 -in file.p12 -clcerts -out file.pem
gmssl pkcs12 -in file.p12 -clcerts -out file.pem
Don't encrypt the private key:
openssl pkcs12 -in file.p12 -out file.pem -nodes
gmssl pkcs12 -in file.p12 -out file.pem -nodes
Print some info about a PKCS#12 file:
openssl pkcs12 -in file.p12 -info -noout
gmssl pkcs12 -in file.p12 -info -noout
Create a PKCS#12 file:
openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
gmssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
Include some extra certificates:
openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
gmssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
-certfile othercerts.pem
=head1 BUGS
Some would argue that the PKCS#12 standard is one big bug :-)
Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation
routines. Under rare circumstances this could produce a PKCS#12 file encrypted
with an invalid key. As a result some PKCS#12 files which triggered this bug
from other implementations (MSIE or Netscape) could not be decrypted
by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could
not be decrypted by other implementations. The chances of producing such
a file are relatively small: less than 1 in 256.
A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
files cannot no longer be parsed by the fixed version. Under such circumstances
the B<pkcs12> utility will report that the MAC is OK but fail with a decryption
error when extracting private keys.
This problem can be resolved by extracting the private keys and certificates
from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12
file from the keys and certificates using a newer version of OpenSSL. For example:
old-openssl -in bad.p12 -out keycerts.pem
openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>
L<pkcs8(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

30
doc/apps/pkcs7.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
pkcs7 - PKCS#7 utility
=head1 SYNOPSIS
B<openssl> B<pkcs7>
B<gmssl> B<pkcs7>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -20,10 +23,14 @@ B<openssl> B<pkcs7>
The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. B<DER> format is DER encoded PKCS#7
@@ -32,7 +39,7 @@ the DER form with header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -73,11 +80,11 @@ for all available algorithms.
Convert a PKCS#7 file from PEM to DER:
openssl pkcs7 -in file.pem -outform DER -out file.der
gmssl pkcs7 -in file.pem -outform DER -out file.der
Output all certificates in a file:
openssl pkcs7 -in file.pem -print_certs -out certs.pem
gmssl pkcs7 -in file.pem -print_certs -out certs.pem
=head1 NOTES
@@ -95,11 +102,20 @@ For compatibility with some CAs it will also accept:
There is no option to print out all the fields of a PKCS#7 file.
This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
cannot currently parse, for example, the new CMS as described in RFC2630.
=head1 SEE ALSO
L<crl2pkcs7(1)|crl2pkcs7(1)>
L<crl2pkcs7(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

198
doc/apps/pkcs8.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
pkcs8 - PKCS#8 format private key conversion tool
=head1 SYNOPSIS
B<openssl> B<pkcs8>
B<gmssl> B<pkcs8>
[B<-help>]
[B<-topk8>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
@@ -14,15 +17,18 @@ B<openssl> B<pkcs8>
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-iter count>]
[B<-noiter>]
[B<-nocrypt>]
[B<-nooct>]
[B<-embed>]
[B<-nsdb>]
[B<-traditional>]
[B<-v2 alg>]
[B<-v2prf alg>]
[B<-v1 alg>]
[B<-engine id>]
[B<-scrypt>]
[B<-scrypt_N N>]
[B<-scrypt_r r>]
[B<-scrypt_p p>]
=head1 DESCRIPTION
@@ -30,28 +36,32 @@ The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-topk8>
Normally a PKCS#8 private key is expected on input and a traditional format
private key will be written. With the B<-topk8> option the situation is
reversed: it reads a traditional format private key and writes a PKCS#8
format key.
Normally a PKCS#8 private key is expected on input and a private key will be
written to the output file. With the B<-topk8> option the situation is
reversed: it reads a private key and writes a PKCS#8 format key.
=item B<-inform DER|PEM>
This specifies the input format. If a PKCS#8 format key is expected on input
then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
expected. Otherwise the B<DER> or B<PEM> format of the traditional format
private key is used.
This specifies the input format: see L<KEY FORMATS> for more details.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
This specifies the output format: see L<KEY FORMATS> for more details.
=item B<-traditional>
When this option is present and B<-topk8> is not a traditional format private
key is written.
=item B<-in filename>
@@ -62,7 +72,7 @@ prompted for.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-out filename>
@@ -74,7 +84,13 @@ filename.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-iter count>
When creating new PKCS#8 containers, use a given number of iterations on
the password in deriving the encryption key for the PKCS#8 output.
High values increase the time required to brute-force a PKCS#8 container.
=item B<-nocrypt>
@@ -85,50 +101,28 @@ This option does not encrypt private keys at all and should only be used
when absolutely necessary. Certain software such as some versions of Java
code signing software used unencrypted private keys.
=item B<-nooct>
This option generates RSA private keys in a broken format that some software
uses. Specifically the private key should be enclosed in a OCTET STRING
but some software just includes the structure itself without the
surrounding OCTET STRING.
=item B<-embed>
This option generates DSA keys in a broken format. The DSA parameters are
embedded inside the PrivateKey structure. In this form the OCTET STRING
contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing
the parameters and an ASN1 INTEGER containing the private key.
=item B<-nsdb>
This option generates DSA keys in a broken format compatible with Netscape
private key databases. The PrivateKey contains a SEQUENCE consisting of
the public and private keys respectively.
=item B<-v2 alg>
This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
private keys are encrypted with the password based encryption algorithm
called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
was the strongest encryption algorithm supported in PKCS#5 v1.5. Using
the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
not many implementations support PKCS#5 v2.0 yet. If you are just using
private keys with OpenSSL then this doesn't matter.
This option sets the PKCS#5 v2.0 algorithm.
The B<alg> argument is the encryption algorithm to use, valid values include
B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256>
is used.
=item B<-v2prf alg>
This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
values would be B<hmacWithSHA256>. If this option isn't set then the default
for the cipher is used or B<hmacWithSHA1> if there is no default.
value would be B<hmacWithSHA256>. If this option isn't set then the default
for the cipher is used or B<hmacWithSHA256> if there is no default.
Some implementations may not support custom PRF algorithms and may require
the B<hmacWithSHA1> option to work.
=item B<-v1 alg>
This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
list of possible algorithms is included below.
This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some
older implementations may not support PKCS#5 v2.0 and may require this option.
If not specified PKCS#5 v2.0 form is used.
=item B<-engine id>
@@ -137,10 +131,49 @@ 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<-scrypt>
uses the B<scrypt> algorithm for private key encryption using default
parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>,
B<-scrypt_p> and B<-v2> options.
B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p>
sets the scrypt B<N>, B<r> or B<p> parameters.
=back
=head1 KEY FORMATS
Various different formats are used by the pkcs8 utility. These are detailed
below.
If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is
not used) then the input file must be in PKCS#8 format. An encrypted
key is expected unless B<-nocrypt> is included.
If B<-topk8> is not used and B<PEM> mode is set the output file will be an
unencrypted private key in PKCS#8 format. If the B<-traditional> option is
used then a traditional format private key is written instead.
If B<-topk8> is not used and B<DER> mode is set the output file will be an
unencrypted private key in traditional DER format.
If B<-topk8> is used then any supported private key can be used for the input
file in a format specified by B<-inform>. The output file will be encrypted
PKCS#8 format using the specified encryption parameters unless B<-nocrypt>
is included.
=head1 NOTES
By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
AES with HMAC and SHA256 is used.
Some older implementations do not support PKCS#5 v2.0 format and require
the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
encryption algorithms such as 56 bit DES.
The encrypted form of a PEM encode PKCS#8 files uses the following
headers and footers:
@@ -157,13 +190,6 @@ counts are more secure that those encrypted using the traditional
SSLeay compatible formats. So if additional security is considered
important the keys should be converted.
The default encryption is only 56 bits because this is the encryption
that most current implementations of PKCS#8 will support.
Some software may use PKCS#12 password based encryption algorithms
with PKCS#8 format private keys: these are handled automatically
but there is no option to produce them.
It is possible to write out DER encoded encrypted private keys in
PKCS#8 format because the encryption details are included at an ASN1
level whereas the traditional format includes them at a PEM level.
@@ -197,33 +223,46 @@ allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
=head1 EXAMPLES
Convert a private from traditional to PKCS#5 v2.0 format using triple
DES:
Convert a private key to PKCS#8 format using default parameters (AES with
256 bit key and B<hmacWithSHA256>):
openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
gmssl pkcs8 -in key.pem -topk8 -out enckey.pem
Convert a private from traditional to PKCS#5 v2.0 format using AES with
256 bits in CBC mode and B<hmacWithSHA256> PRF:
Convert a private key to PKCS#8 unencrypted format:
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
gmssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
Convert a private key to PKCS#5 v2.0 format using triple DES:
gmssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
mode and B<hmacWithSHA512> PRF:
gmssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
(DES):
openssl pkcs8 -in key.pem -topk8 -out enckey.pem
gmssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
(3DES):
openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
gmssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
Read a DER unencrypted PKCS#8 format private key:
openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
gmssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
Convert a private key from any PKCS#8 format to traditional format:
Convert a private key from any PKCS#8 encrypted format to traditional format:
openssl pkcs8 -in pk8.pem -out key.pem
gmssl pkcs8 -in pk8.pem -traditional -out key.pem
Convert a private key to PKCS#8 format, encrypting with AES-256 and with
one million iterations of the password:
gmssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
=head1 STANDARDS
@@ -235,7 +274,7 @@ implementation is reasonably accurate at least as far as these
algorithms are concerned.
The format of PKCS#8 DSA (and other) private keys is not well documented:
it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
it is hidden away in PKCS#11 v2.01, section 11.9. GmSSL's default DSA
PKCS#8 private key format complies with this standard.
=head1 BUGS
@@ -243,13 +282,22 @@ PKCS#8 private key format complies with this standard.
There should be an option that prints out the encryption algorithm
in use and other details such as the iteration count.
PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
key format for OpenSSL: for compatibility several of the utilities use
the old format at present.
=head1 SEE ALSO
L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>
L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
L<gendsa(1)>
=head1 HISTORY
The B<-iter> option was added to GmSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

92
doc/apps/pkey.pod
View File

@@ -1,19 +1,22 @@
=pod
=encoding utf8
=head1 NAME
pkey - public or private key processing tool
=head1 SYNOPSIS
B<openssl> B<pkey>
B<gmssl> B<pkey>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-traditional>]
[B<-cipher>]
[B<-text>]
[B<-text_pub>]
@@ -27,29 +30,47 @@ B<openssl> B<pkey>
The B<pkey> command processes public or private keys. They can be converted
between various forms and their components printed out.
=head1 COMMAND OPTIONS
pkey指令处理公钥或者私钥。
它们可以在各种形式之间进行转换，并将其组件打印出来。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
打印使用信息。
=item B<-inform DER|PEM>
This specifies the input format DER or PEM.
该选项指出了输入格式是DER还是PEM。
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
该选项指出了输出格式，与-inform意义相同。
=item B<-in filename>
This specifies the input filename to read a key from or standard input if this
option is not specified. If the key is encrypted a pass phrase will be
prompted for.
如果该选项没有被指定，则指定从密钥中读取输入文件名或者标准输入。
如果密钥被加密，将提示输入密码。
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
输入文件的密码来源。有关arg格式的更多信息，请参阅gmssl（1）中的PASS PHRASE ARGUMENTS部分。
=item B<-out filename>
@@ -58,40 +79,67 @@ option is not specified. If any encryption options are set then a pass phrase
will be prompted for. The output filename should B<not> be the same as the input
filename.
如果未指定此选项，则指定将密钥写入或输出的输出文件名。 如果设置了任何加密选项，
则会提示输入密码。 输出文件名不能与输入文件名相同。
=item B<-passout password>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
输出文件的密码来源。有关arg格式的更多信息请参阅gmssl(1)中的PASS PHARSE ARGUMENTS部分。
=item B<-traditional>
normally a private key is written using standard format: this is PKCS#8 form
with the appropriate encryption algorithm (if any). If the B<-traditional>
option is specified then the older "traditional" format is used instead.
通常使用标准格式写入私钥：这是具有适当加密算法（如果有的话）的PKCS＃8表单。
如果指定了-traditional选项，则使用较旧的“traditional”格式。
=item B<-cipher>
These options encrypt the private key with the supplied cipher. Any algorithm
name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
这些选项使用提供的密码加密私钥。 EVP_get_cipherbyname（）接受的任何算法名称都可以接受，如des3。
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
plain text in addition to the encoded version.
除了编码版本之外，以纯文本形式打印各种公共或私人密钥组件。
=item B<-text_pub>
print out only public key components even if a private key is being processed.
即使正在处理私钥，也打印公钥组件。
=item B<-noout>
do not output the encoded version of the key.
不打印出密钥的编码版本信息。
=item B<-pubin>
by default a private key is read from the input file: with this
option a public key is read instead.
默认从输入文件读取一个私钥：使用该选项后则变为读取一个公钥。
=item B<-pubout>
by default a private key is output: with this option a public
key will be output instead. This option is automatically set if
the input is a public key.
默认是输出一个私钥：使用该选项后则变为输出一个公钥。如果输入是公钥则该选项会自动设置。
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<pkey>
@@ -99,37 +147,49 @@ 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.
指定要使用的硬件引擎。指定一个引擎（通过其唯一的id字符串）将导致pkey尝试获取对指定引擎的功能引用
，从而如果需要的话初始化它。 然后，引擎将被设置为所有可用算法的默认值。
=back
=head1 EXAMPLES
To remove the pass phrase on an RSA private key:
openssl pkey -in key.pem -out keyout.pem
gmssl pkey -in key.pem -out keyout.pem
To encrypt a private key using triple DES:
openssl pkey -in key.pem -des3 -out keyout.pem
gmssl pkey -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
To convert a private key from PEM to DER format:
openssl pkey -in key.pem -outform DER -out keyout.der
gmssl pkey -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl pkey -in key.pem -text -noout
gmssl pkey -in key.pem -text -noout
To print out the public components of a private key to standard output:
openssl pkey -in key.pem -text_pub -noout
gmssl pkey -in key.pem -text_pub -noout
To just output the public part of a private key:
openssl pkey -in key.pem -pubout -out pubkey.pem
gmssl pkey -in key.pem -pubout -out pubkey.pem
=head1 SEE ALSO
L<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>,
L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)>
L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

29
doc/apps/pkeyparam.pod
View File

@@ -1,13 +1,15 @@
=pod
=encoding utf8
=head1 NAME
pkeyparam - public key algorithm parameter processing tool
=head1 SYNOPSIS
B<openssl> B<pkeyparam>
B<gmssl> B<pkeyparam>
[B<-help>]
[B<-in filename>]
[B<-out filename>]
[B<-text>]
@@ -19,10 +21,14 @@ B<openssl> B<pkeyparam>
The B<pkey> command processes public or private keys. They can be converted
between various forms and their components printed out.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read parameters from or standard input if
@@ -35,7 +41,7 @@ this option is not specified.
=item B<-text>
prints out the parameters in plain text in addition to the encoded version.
prints out the parameters in plain text in addition to the encoded version.
=item B<-noout>
@@ -54,7 +60,7 @@ for all available algorithms.
Print out text version of parameters:
openssl pkeyparam -in param.pem -text
gmssl pkeyparam -in param.pem -text
=head1 NOTES
@@ -63,7 +69,16 @@ PEM format is supported because the key type is determined by the PEM headers.
=head1 SEE ALSO
L<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>,
L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)>
L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

125
doc/apps/pkeyutl.pod
View File

@@ -1,20 +1,23 @@
=pod
=encoding utf8
=head1 NAME
pkeyutl - public key algorithm utility
=head1 SYNOPSIS
B<openssl> B<pkeyutl>
B<gmssl> B<pkeyutl>
[B<-help>]
[B<-in file>]
[B<-out file>]
[B<-sigfile file>]
[B<-inkey file>]
[B<-keyform PEM|DER>]
[B<-keyform PEM|DER|ENGINE>]
[B<-passin arg>]
[B<-peerkey file>]
[B<-peerform PEM|DER>]
[B<-peerform PEM|DER|ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-rev>]
@@ -24,20 +27,27 @@ B<openssl> B<pkeyutl>
[B<-encrypt>]
[B<-decrypt>]
[B<-derive>]
[B<-kdf algorithm>]
[B<-kdflen length>]
[B<-pkeyopt opt:value>]
[B<-hexdump>]
[B<-asn1parse>]
[B<-engine id>]
[B<-engine_impl>]
=head1 DESCRIPTION
The B<pkeyutl> command can be used to perform public key operations using
any supported algorithm.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read data from or standard input
@@ -48,43 +58,39 @@ if this option is not specified.
specifies the output filename to write to or standard output by
default.
=item B<-sigfile file>
Signature file, required for B<verify> operations only
=item B<-inkey file>
the input key file, by default it should be a private key.
=item B<-keyform PEM|DER>
=item B<-keyform PEM|DER|ENGINE>
the key format PEM, DER or ENGINE.
the key format PEM, DER or ENGINE. Default is PEM.
=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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-peerkey file>
the peer key file, used by key derivation (agreement) operations.
=item B<-peerform PEM|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<-peerform PEM|DER|ENGINE>
the peer key format PEM, DER or ENGINE. Default is PEM.
=item B<-pubin>
the input file is a public key.
the input file is a public key.
=item B<-certin>
the input is a certificate containing a public key.
the input is a certificate containing a public key.
=item B<-rev>
@@ -117,6 +123,23 @@ decrypt the input data using a private key.
derive a shared secret using the peer key.
=item B<-kdf algorithm>
Use key derivation function B<algorithm>. The supported algorithms are
at present B<TLS1-PRF> and B<HKDF>.
Note: additional parameters and the KDF output length will normally have to be
set for this to work.
See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
for the supported string parameters of each algorithm.
=item B<-kdflen length>
Set the output length for KDF.
=item B<-pkeyopt opt:value>
Public key options specified as opt:value. See NOTES below for more details.
=item B<-hexdump>
hex dump the output data.
@@ -126,12 +149,24 @@ hex dump the output data.
asn1parse the output data, this is useful when combined with the
B<-verifyrecover> option when an ASN1 structure is signed.
=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<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine B<id> for crypto operations.
=back
=head1 NOTES
The operations and options supported vary according to the key algorithm
and its implementation. The OpenSSL operations and options are indicated below.
and its implementation. The GmSSL operations and options are indicated below.
Unless otherwise mentioned all algorithms support the B<digest:alg> option
which specifies the digest in use for sign, verify and verifyrecover operations.
@@ -153,24 +188,25 @@ long binary encoding of SHA-1 hash function output.
=head1 RSA ALGORITHM
The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover
operations in general. Some padding modes only support some of these
operations however.
The RSA algorithm generally supports the encrypt, decrypt, sign,
verify and verifyrecover operations. However, some padding modes
support only a subset of these operations. The following additional
B<pkeyopt> values are supported:
=over 4
=item -B<rsa_padding_mode:mode>
=item B<rsa_padding_mode:mode>
This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for
PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep>
for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
In PKCS#1 padding if the message digest is not set then the supplied data is
In PKCS#1 padding if the message digest is not set then the supplied data is
signed or verified directly instead of using a B<DigestInfo> structure. If a
digest is set then the a B<DigestInfo> structure is used and its the length
must correspond to the digest type.
For B<oeap> mode only encryption and decryption is supported.
For B<oaep> mode only encryption and decryption is supported.
For B<x931> if the digest type is set it is used to format the block data
otherwise the first byte is used to specify the X9.31 digest ID. Sign,
@@ -207,29 +243,52 @@ verify operations use ECDSA and derive uses ECDH. Currently there are no
additional options other than B<digest>. Only the SHA1 digest can be used and
this digest is assumed by default.
=head1 X25519 ALGORITHM
The X25519 algorithm supports key derivation only. Currently there are no
additional options.
=head1 EXAMPLES
Sign some data using a private key:
openssl pkeyutl -sign -in file -inkey key.pem -out sig
gmssl pkeyutl -sign -in file -inkey key.pem -out sig
Recover the signed data (e.g. if an RSA key is used):
openssl pkeyutl -verifyrecover -in sig -inkey key.pem
gmssl pkeyutl -verifyrecover -in sig -inkey key.pem
Verify the signature (e.g. a DSA key):
openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
gmssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
Sign data using a message digest value (this is currently only valid for RSA):
openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
gmssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
Derive a shared secret value:
openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
gmssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and
seed consisting of the single byte 0xFF:
gmssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
-pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
=head1 SEE ALSO
L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)>
L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>
L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

42
doc/apps/rand.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
rand - generate pseudo-random bytes
=head1 SYNOPSIS
B<openssl rand>
B<gmssl rand>
[B<-help>]
[B<-out> I<file>]
[B<-rand> I<file(s)>]
[B<-base64>]
@@ -16,40 +19,69 @@ I<num>
=head1 DESCRIPTION
The B<rand> command outputs I<num> pseudo-random bytes after seeding
the random number generator once. As in other B<openssl> command
the random number generator once. As in other B<gmssl> command
line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd>
in addition to the files given in the B<-rand> option. A new
I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough
seeding was obtained from these sources.
rand命令在播放随机数生成器一次后输出num伪随机字节。 与其他gmssl命令行工具一样，
除了-rand选项中提供的文件外，PRNG种子使用文件$ HOME / .rnd或.rnd。
如果从这些来源获得足够的播种，将会写入新的$ HOME / .rnd或.rnd文件。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
输出使用信息
=item B<-out> I<file>
Write to I<file> instead of standard output.
写入file而不是标准输出。
=item B<-rand> I<file(s)>
Use specified file or files or EGD socket (see L<RAND_egd(3)|RAND_egd(3)>)
Use specified file or files or EGD socket (see L<RAND_egd(3)>)
for seeding the random number generator.
Multiple files can be specified separated by a OS-dependent character.
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
使用指定的文件或EGD套接字（请参阅RAND_egd（3））播放随机数生成器。
多个文件可以由与操作系统相关的字符分隔。 分离器是 对于MS-Windows，对于OpenVMS
，以及：对于所有其他。
=item B<-base64>
Perform base64 encoding on the output.
在输出上执行base64编码。
=item B<-hex>
Show the output as a hex string.
将输出显示为十六进制字符串。
=back
=head1 SEE ALSO
L<RAND_bytes(3)|RAND_bytes(3)>
L<RAND_bytes(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

208
doc/apps/req.pod
View File

@@ -1,13 +1,15 @@
=pod
=encoding utf8
=head1 NAME
req - PKCS#10 certificate request and certificate generating utility.
req - PKCS#10 certificate request and certificate generating utility
=head1 SYNOPSIS
B<openssl> B<req>
B<gmssl> B<req>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -34,8 +36,6 @@ B<openssl> B<req>
[B<-x509>]
[B<-days n>]
[B<-set_serial n>]
[B<-asn1-kludge>]
[B<-no-asn1-kludge>]
[B<-newhdr>]
[B<-extensions section>]
[B<-reqexts section>]
@@ -54,10 +54,14 @@ The B<req> command primarily creates and processes certificate requests
in PKCS#10 format. It can additionally create self signed certificates
for use as root CAs for example.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -67,7 +71,7 @@ footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -79,7 +83,7 @@ options (B<-new> and B<-newkey>) are not specified.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-out filename>
@@ -89,7 +93,7 @@ default.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-text>
@@ -127,18 +131,11 @@ 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
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -152,13 +149,13 @@ 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.
or and X.509 certificate for a key with appropriate 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.
if necessary 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
@@ -198,8 +195,9 @@ will not be encrypted.
=item B<-[digest]>
this specifies the message digest to sign the request with (such as
B<-md5>, B<-sha1>). This overrides the digest algorithm specified in
this specifies the message digest to sign the request.
Any digest supported by the GmSSL B<dgst> command can be used.
This overrides the digest algorithm specified in
the configuration file.
Some public key algorithms may override this choice. For instance, DSA
@@ -224,7 +222,7 @@ characters may be escaped by \ (backslash), no spaces are skipped.
this option causes the -subj argument to be interpreted with full
support for multivalued RDNs. Example:
I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
I</DC=org/DC=GmSSL/DC=users/UID=123456+CN=John Doe>
If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
@@ -237,9 +235,6 @@ a self signed root CA. The extensions added to the certificate
using the B<set_serial> option, a large random number will be used for
the serial number.
If existing request is specified with the B<-in> option, it is converted
to the self signed certificate otherwise new request is created.
=item B<-days n>
when the B<-x509> option is being used this specifies the number of
@@ -263,7 +258,7 @@ a variety of purposes.
=item B<-utf8>
this option causes field values to be interpreted as UTF8 strings, by
this option causes field values to be interpreted as UTF8 strings, by
default they are interpreted as ASCII. This means that the field
values, whether prompted from a terminal or obtained from a
configuration file, must be valid UTF8 strings.
@@ -273,36 +268,16 @@ configuration file, must be valid UTF8 strings.
option which determines how the subject or issuer names are displayed. The
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.
set multiple options. See the L<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.
a single option or multiple options separated by commas.
See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)>
See discussion of the B<-certopt> parameter in the L<x509(1)>
command.
=item B<-asn1-kludge>
by default the B<req> command outputs certificate requests containing
no attributes in the correct PKCS#10 format. However certain CAs will only
accept requests containing no attributes in an invalid form: this
option produces this invalid format.
More precisely the B<Attributes> in a PKCS#10 certificate request
are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
if no attributes are present then they should be encoded as an
empty B<SET OF>. The invalid form does not include the empty
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 outputted
@@ -368,7 +343,7 @@ overridden by the B<-keyout> option.
This specifies a file containing additional B<OBJECT IDENTIFIERS>.
Each line of the file should consist of the numerical form of the
object identifier followed by white space then the short name followed
by white space and finally the long name.
by white space and finally the long name.
=item B<oid_section>
@@ -380,7 +355,7 @@ and long names are the same when this option is used.
=item B<RANDFILE>
This specifies a filename in which random number seed information is
placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
placed and read from, or an EGD socket (see L<RAND_egd(3)>).
It is used for private key generation.
=item B<encrypt_key>
@@ -391,9 +366,10 @@ option. For compatibility B<encrypt_rsa_key> is an equivalent option.
=item B<default_md>
This option specifies the digest algorithm to use. Possible values
include B<md5 sha1 mdc2>. If not present then MD5 is used. This
option can be overridden on the command line.
This option specifies the digest algorithm to use.
Any digest supported by the GmSSL B<dgst> command can be used.
If not present then MD5 is used.
This option can be overridden on the command line.
=item B<string_mask>
@@ -401,7 +377,7 @@ This option masks out the use of certain string types in certain
fields. Most users will not need to change this option.
It can be set to several values B<default> which is also the default
option uses PrintableStrings, T61Strings and BMPStrings if the
option uses PrintableStrings, T61Strings and BMPStrings if the
B<pkix> value is used then only PrintableStrings and BMPStrings will
be used. This follows the PKIX recommendation in RFC2459. If the
B<utf8only> option is used then only UTF8Strings will be used: this
@@ -413,8 +389,8 @@ problems with BMPStrings and UTF8Strings: in particular Netscape.
this specifies the configuration file section containing a list of
extensions to add to the certificate request. It can be overridden
by the B<-reqexts> command line switch. See the
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
by the B<-reqexts> command line switch. See the
L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<x509_extensions>
@@ -441,7 +417,7 @@ configuration file, must be valid UTF8 strings.
this specifies the section containing any request attributes: its format
is the same as B<distinguished_name>. Typically these may contain the
challengePassword or unstructuredName types. They are currently ignored
by OpenSSL's request signing utilities but some CAs might want them.
by GmSSL's request signing utilities but some CAs might want them.
=item B<distinguished_name>
@@ -493,7 +469,7 @@ they will be ignored. So for example a second organizationName can
be input by calling it "1.organizationName".
The actual permitted field names are any object identifier short or
long names. These are compiled into OpenSSL and include the usual
long names. These are compiled into GmSSL and include the usual
values such as commonName, countryName, localityName, organizationName,
organizationalUnitName, stateOrProvinceName. Additionally emailAddress
is include as well as name, surname, givenName initials and dnQualifier.
@@ -507,25 +483,25 @@ will be treated as though they were a DirectoryString.
Examine and verify certificate request:
openssl req -in req.pem -text -verify -noout
gmssl req -in req.pem -text -verify -noout
Create a private key and then generate a certificate request from it:
openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out req.pem
gmssl genrsa -out key.pem 2048
gmssl req -new -key key.pem -out req.pem
The same but just using req:
openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
gmssl req -newkey rsa:2048 -keyout key.pem -out req.pem
Generate a self signed root certificate:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
gmssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
Example of a file pointed to by the B<oid_file> option:
1.2.3.4 shortName A longer Name
1.2.3.6 otherName Other longer Name
1.2.3.4 shortName A longer Name
1.2.3.6 otherName Other longer Name
Example of a section pointed to by B<oid_section> making use of variable
expansion:
@@ -536,65 +512,65 @@ expansion:
Sample configuration file prompting for field values:
[ req ]
default_bits = 2048
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
x509_extensions = v3_ca
default_bits = 2048
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
req_extensions = v3_ca
dirstring_type = nobmp
[ req_distinguished_name ]
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
localityName = Locality Name (eg, city)
localityName = Locality Name (eg, city)
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName = Organizational Unit Name (eg, section)
commonName = Common Name (eg, YOUR name)
commonName_max = 64
commonName = Common Name (eg, YOUR name)
commonName_max = 64
emailAddress = Email Address
emailAddress_max = 40
emailAddress = Email Address
emailAddress_max = 40
[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
[ v3_ca ]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always
basicConstraints = CA:true
basicConstraints = critical, CA:true
Sample configuration containing all field values:
RANDFILE = $ENV::HOME/.rnd
RANDFILE = $ENV::HOME/.rnd
[ req ]
default_bits = 2048
default_keyfile = keyfile.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
prompt = no
output_password = mypass
default_bits = 2048
default_keyfile = keyfile.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
prompt = no
output_password = mypass
[ req_distinguished_name ]
C = GB
ST = Test State or Province
L = Test Locality
O = Organization Name
OU = Organizational Unit Name
CN = Common Name
emailAddress = test@email.address
C = GB
ST = Test State or Province
L = Test Locality
O = Organization Name
OU = Organizational Unit Name
CN = Common Name
emailAddress = test@email.address
[ req_attributes ]
challengePassword = A challenge password
challengePassword = A challenge password
=head1 NOTES
@@ -621,13 +597,13 @@ by the script in an extendedKeyUsage extension.
The following messages are frequently asked about:
Using configuration from /some/path/openssl.cnf
Unable to load config info
Using configuration from /some/path/openssl.cnf
Unable to load config info
This is followed some time later by...
unable to find 'distinguished_name' in config
problems making Certificate Request
unable to find 'distinguished_name' in config
problems making Certificate Request
The first error message is the clue: it can't find the configuration
file! Certain operations (like examining a certificate request) don't
@@ -654,18 +630,17 @@ for more information.
The variable B<OPENSSL_CONF> if defined allows an alternative configuration
file location to be specified, it will be overridden by the B<-config> command
line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
environment variable serves the same purpose but its use is discouraged.
line switch if it is present.
=head1 BUGS
OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
GmSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
This can cause problems if you need characters that aren't available in
PrintableStrings and you don't want to or can't use BMPStrings.
As a consequence of the T61String handling the only correct way to represent
accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
accented characters in GmSSL is to use a BMPString: unfortunately Netscape
currently chokes on these. If you have to use accented characters with Netscape
and MSIE then you currently need to use the invalid T61String form.
@@ -676,8 +651,17 @@ address in subjectAltName should be input by the user.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>,
L<x509v3_config(5)|x509v3_config(5)>
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
L<gendsa(1)>, L<config(5)>,
L<x509v3_config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

56
doc/apps/rsa.pod
View File

@@ -1,20 +1,21 @@
=pod
=encoding utf8
=head1 NAME
rsa - RSA key processing tool
=head1 SYNOPSIS
B<openssl> B<rsa>
B<gmssl> B<rsa>
[B<-help>]
[B<-inform PEM|NET|DER>]
[B<-outform PEM|NET|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-sgckey>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
@@ -42,10 +43,14 @@ traditional SSLeay compatible format for private key encryption: newer
applications should use the more secure PKCS#8 format using the B<pkcs8>
utility.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|NET|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -57,7 +62,7 @@ section.
=item B<-outform DER|NET|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -69,7 +74,7 @@ prompted for.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-out filename>
@@ -81,12 +86,7 @@ filename.
=item B<-passout password>
the output file 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<-sgckey>
use the modified NET algorithm used with some versions of Microsoft IIS and SGC
keys.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
@@ -101,7 +101,7 @@ These options can only be used with PEM format output files.
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
plain text in addition to the encoded version.
=item B<-noout>
@@ -165,34 +165,33 @@ files. To use these with the utility, view the file with a binary editor
and look for the string "private-key", then trace back to the byte
sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data
from this point onwards to another file and use that as the input
to the B<rsa> utility with the B<-inform NET> option. If you get
an error after entering the password try the B<-sgckey> option.
to the B<rsa> utility with the B<-inform NET> option.
=head1 EXAMPLES
To remove the pass phrase on an RSA private key:
openssl rsa -in key.pem -out keyout.pem
gmssl rsa -in key.pem -out keyout.pem
To encrypt a private key using triple DES:
openssl rsa -in key.pem -des3 -out keyout.pem
gmssl rsa -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
To convert a private key from PEM to DER format:
openssl rsa -in key.pem -outform DER -out keyout.der
gmssl rsa -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl rsa -in key.pem -text -noout
gmssl rsa -in key.pem -text -noout
To just output the public part of a private key:
openssl rsa -in key.pem -pubout -out pubkey.pem
gmssl rsa -in key.pem -pubout -out pubkey.pem
Output the public part of a private key in B<RSAPublicKey> format:
openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem
gmssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem
=head1 BUGS
@@ -204,7 +203,16 @@ without having to manually edit them.
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>
L<pkcs8(1)>, L<dsa(1)>, L<genrsa(1)>,
L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

85
doc/apps/rsautl.pod
View File

@@ -1,15 +1,19 @@
=pod
=encoding utf8
=head1 NAME
rsautl - RSA utility
=head1 SYNOPSIS
B<openssl> B<rsautl>
B<gmssl> B<rsautl>
[B<-help>]
[B<-in file>]
[B<-out file>]
[B<-inkey file>]
[B<-keyform PEM|DER|ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-sign>]
@@ -27,10 +31,14 @@ B<openssl> B<rsautl>
The B<rsautl> command can be used to sign, verify, encrypt and decrypt
data using the RSA algorithm.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read data from or standard input
@@ -45,18 +53,22 @@ default.
the input key file, by default it should be an RSA private key.
=item B<-keyform PEM|DER|ENGINE>
the key format PEM, DER or ENGINE.
=item B<-pubin>
the input file is an RSA public key.
the input file is an RSA public key.
=item B<-certin>
the input is a certificate containing an RSA public key.
the input is a certificate containing an RSA public key.
=item B<-sign>
sign the input data and output the signed result. This requires
and RSA private key.
an RSA private key.
=item B<-verify>
@@ -97,15 +109,15 @@ used to sign or verify small pieces of data.
Sign some data using a private key:
openssl rsautl -sign -in file -inkey key.pem -out sig
gmssl rsautl -sign -in file -inkey key.pem -out sig
Recover the signed data
openssl rsautl -verify -in sig -inkey key.pem
gmssl rsautl -verify -in sig -inkey key.pem
Examine the raw signed data:
openssl rsautl -verify -in file -inkey key.pem -raw -hexdump
gmssl rsautl -verify -in file -inkey key.pem -raw -hexdump
0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
@@ -124,60 +136,71 @@ It is possible to analyse the signature of certificates using this
utility in conjunction with B<asn1parse>. Consider the self signed
example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
openssl asn1parse -in pca-cert.pem
gmssl asn1parse -in pca-cert.pem
0:d=0 hl=4 l= 742 cons: SEQUENCE
4:d=1 hl=4 l= 591 cons: SEQUENCE
8:d=2 hl=2 l= 3 cons: cont [ 0 ]
0:d=0 hl=4 l= 742 cons: SEQUENCE
4:d=1 hl=4 l= 591 cons: SEQUENCE
8:d=2 hl=2 l= 3 cons: cont [ 0 ]
10:d=3 hl=2 l= 1 prim: INTEGER :02
13:d=2 hl=2 l= 1 prim: INTEGER :00
16:d=2 hl=2 l= 13 cons: SEQUENCE
16:d=2 hl=2 l= 13 cons: SEQUENCE
18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
29:d=3 hl=2 l= 0 prim: NULL
31:d=2 hl=2 l= 92 cons: SEQUENCE
33:d=3 hl=2 l= 11 cons: SET
35:d=4 hl=2 l= 9 cons: SEQUENCE
29:d=3 hl=2 l= 0 prim: NULL
31:d=2 hl=2 l= 92 cons: SEQUENCE
33:d=3 hl=2 l= 11 cons: SET
35:d=4 hl=2 l= 9 cons: SEQUENCE
37:d=5 hl=2 l= 3 prim: OBJECT :countryName
42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU
....
599:d=1 hl=2 l= 13 cons: SEQUENCE
599:d=1 hl=2 l= 13 cons: SEQUENCE
601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
612:d=2 hl=2 l= 0 prim: NULL
614:d=1 hl=3 l= 129 prim: BIT STRING
612:d=2 hl=2 l= 0 prim: NULL
614:d=1 hl=3 l= 129 prim: BIT STRING
The final BIT STRING contains the actual signature. It can be extracted with:
openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
gmssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
The certificate public key can be extracted with:
openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
gmssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
The signature can be analysed with:
openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
gmssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
0:d=0 hl=2 l= 32 cons: SEQUENCE
2:d=1 hl=2 l= 12 cons: SEQUENCE
0:d=0 hl=2 l= 32 cons: SEQUENCE
2:d=1 hl=2 l= 12 cons: SEQUENCE
4:d=2 hl=2 l= 8 prim: OBJECT :md5
14:d=2 hl=2 l= 0 prim: NULL
16:d=1 hl=2 l= 16 prim: OCTET STRING
14:d=2 hl=2 l= 0 prim: NULL
16:d=1 hl=2 l= 16 prim: OCTET STRING
0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%..
This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
the digest used was md5. The actual part of the certificate that was signed can
be extracted with:
openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
gmssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
and its digest computed with:
openssl md5 -c tbs
gmssl md5 -c tbs
MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
which it can be seen agrees with the recovered value above.
=head1 SEE ALSO
L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

479
doc/apps/s_client.pod
View File

@@ -1,14 +1,20 @@
=pod
=encoding utf8
=head1 NAME
s_client - SSL/TLS client program
=head1 SYNOPSIS
B<openssl> B<s_client>
B<gmssl> B<s_client>
[B<-help>]
[B<-connect host:port>]
[B<-proxy host:port>]
[B<-unix path>]
[B<-4>]
[B<-6>]
[B<-servername name>]
[B<-verify depth>]
[B<-verify_return_error>]
@@ -19,9 +25,40 @@ B<openssl> B<s_client>
[B<-pass arg>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-dane_tlsa_domain domain>]
[B<-dane_tlsa_rrdata rrdata>]
[B<-dane_ee_no_namechecks>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-reconnect>]
[B<-pause>]
[B<-showcerts>]
[B<-debug>]
[B<-msg>]
@@ -32,21 +69,31 @@ B<openssl> B<s_client>
[B<-ign_eof>]
[B<-no_ign_eof>]
[B<-quiet>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-no_ssl2>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-tls1_3>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-no_tls1_3>]
[B<-dtls>]
[B<-dtls1>]
[B<-dtls1_2>]
[B<-fallback_scsv>]
[B<-async>]
[B<-split_send_frag>]
[B<-max_pipelines>]
[B<-read_buf>]
[B<-bugs>]
[B<-sigalgs sigalglist>]
[B<-curves curvelist>]
[B<-comp>]
[B<-no_comp>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-starttls protocol>]
[B<-xmpphost hostname>]
[B<-engine id>]
[B<-tlsextdebug>]
[B<-no_ticket>]
@@ -57,6 +104,8 @@ B<openssl> B<s_client>
[B<-status>]
[B<-alpn protocols>]
[B<-nextprotoneg protocols>]
[B<-ct|noct>]
[B<-ctlogfile>]
=head1 DESCRIPTION
@@ -64,41 +113,96 @@ The B<s_client> command implements a generic SSL/TLS client which connects
to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for
SSL servers.
s_client命令实现使用SSL / TLS连接到远程主机的通用SSL / TLS客户端。 它是SSL服务器非常有用的诊断工具。
=head1 OPTIONS
In addition to the options below the B<s_client> utility also supports the
common and client only options documented in the
in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
manual page.
除了以下选项之外，s_client实用程序还支持SSL_CONF_cmd（3）手册页的“支持的命令行命令”部分中记录的通用和客户端选项。
=over 4
=item B<-help>
Print out a usage message.
输出使用信息。
=item B<-connect host:port>
This specifies the host and optional port to connect to. If not specified
then an attempt is made to connect to the local host on port 4433.
这指定要连接的主机和可选端口。 如果未指定，则尝试连接到端口4433上的本地主机。
=item B<-proxy host:port>
When used with the B<-connect> flag, the program uses the host and port
specified with this flag and issues an HTTP CONNECT command to connect
to the desired server.
当与-connect标志一起使用时，程序使用由该标志指定的主机和端口，并发出HTTP CONNECT命令连接到所需的服务器。
=item B<-unix path>
Connect over the specified Unix-domain socket.
连接指定的Unix域套接字。
=item B<-4>
Use IPv4 only.
仅使用IPv4。
=item B<-6>
Use IPv6 only.
仅使用IPv6.
=item B<-servername name>
Set the TLS SNI (Server Name Indication) extension in the ClientHello message.
在ClientHello消息中设置TLS SNI（服务器名称指示）扩展。
=item B<-cert certname>
The certificate to use, if one is requested by the server. The default is
not to use a certificate.
要使用的证书，如果是服务器请求的。 默认情况下不使用证书。
=item B<-certform format>
The certificate format to use: DER or PEM. PEM is the default.
使用的证书格式：DER或PEM。 PEM是默认值。
=item B<-key keyfile>
The private key to use. If not specified then the certificate file will
be used.
使用私钥。 如果未指定，则将使用证书文件。
=item B<-keyform format>
The private format to use: DER or PEM. PEM is the default.
要使用的私有格式：DER或PEM。 PEM是默认值。
=item B<-pass arg>
the private 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
私钥密码源。 有关arg格式的更多信息，请参阅gmssl（1）中的PASS PHRASE ARGUMENTS部分。
=item B<-verify depth>
@@ -108,41 +212,144 @@ Currently the verify operation continues after errors so all the problems
with a certificate chain can be seen. As a side effect the connection
will never fail due to a server certificate verify failure.
验证使用深度。 这指定服务器证书链的最大长度，并打开服务器证书验证。
目前，验证操作在错误之后继续，所以可以看到证书链中的所有问题。
作为副作用，由于服务器证书验证失败，连接永远不会失败。
=item B<-verify_return_error>
Return verification errors instead of continuing. This will typically
abort the handshake with a fatal error.
返回验证错误，而不是继续。 这通常会以致命错误中止握手。
=item B<-CApath directory>
The directory to use for server certificate verification. This directory
must be in "hash format", see B<verify> for more information. These are
also used when building the client certificate chain.
用于服务器证书验证的目录。 此目录必须为“哈希格式”，请参阅验证更多信息。 这些也在构建客户端证书链时使用。
=item B<-CAfile file>
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 -check_ss_sig -no_alt_chains>
包含在服务器认证期间使用并在尝试构建客户端证书链时使用的可信证书的文件。
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
不要从默认文件位置加载受信任的CA证书
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
不要从默认目录位置加载受信任的CA证书
=item B<-dane_tlsa_domain domain>
Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
TLSA base domain which becomes the default SNI hint and the primary
reference identifier for hostname checks. This must be used in
combination with at least one instance of the B<-dane_tlsa_rrdata>
option below.
When DANE authentication succeeds, the diagnostic output will include
the lowest (closest to 0) depth at which a TLSA record authenticated
a chain certificate. When that TLSA record is a "2 1 0" trust
anchor public key that signed (rather than matched) the top-most
certificate of the chain, the result is reported as "TA public key
verified". Otherwise, either the TLSA record "matched TA certificate"
at a positive depth or else "matched EE certificate" at depth 0.
启用RFC6698 / RFC7671 DANE TLSA身份验证，并指定成为默认SNI提示的TLSA基本域和主机名检查的主参考标识符。
这必须与以下-dane_tlsa_rrdata选项的至少一个实例结合使用。
当DANE认证成功时，诊断输出将包括TLSA记录认证链式证书的最低（最接近0）深度。
当该TLSA记录是一个“2 1 0”信任锚公钥，该信任锚公钥是签名（而不是匹配）链中最顶层的证书，
结果被报告为“TA公钥验证”。 否则，TLSA记录“匹配的TA证书”在深度为深度，否则“匹配的EE证书”在深度0。
=item B<-dane_tlsa_rrdata rrdata>
Use one or more times to specify the RRDATA fields of the DANE TLSA
RRset associated with the target service. The B<rrdata> value is
specied in "presentation form", that is four whitespace separated
fields that specify the usage, selector, matching type and associated
data, with the last of these encoded in hexadecimal. Optional
whitespace is ignored in the associated data field. For example:
使用一次或多次来指定与目标服务相关联的DANE TLSA RRset的RRDATA字段。
rrdata值以“表示形式”指定，即指定使用，选择器，匹配类型和关联数据的
四个空白分隔字段，其中最后一个以十六进制编码。 可选的空格在关联的数据字段中被忽略。 例如：
$ gmssl s_client -brief -starttls smtp \
-connect smtp.example.com:25 \
-dane_tlsa_domain smtp.example.com \
-dane_tlsa_rrdata "2 1 1
B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \
-dane_tlsa_rrdata "2 1 1
60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18"
...
Verification: OK
Verified peername: smtp.example.com
DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1
...
=item B<-dane_ee_no_namechecks>
This disables server name checks when authenticating via DANE-EE(3) TLSA
records.
For some applications, primarily web browsers, it is not safe to disable name
checks due to "unknown key share" attacks, in which a malicious server can
convince a client that a connection to a victim server is instead a secure
connection to the malicious server.
The malicious server may then be able to violate cross-origin scripting
restrictions.
Thus, despite the text of RFC7671, name checks are by default enabled for
DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
to do so.
In particular, SMTP and XMPP clients should set this option as SRV and MX
records already make it possible for a remote domain to redirect client
connections to any server of its choice, and in any case SMTP and XMPP clients
do not execute scripts downloaded from remote servers.
当通过DANE-EE（3）TLSA记录进行身份验证时，这将禁用服务器名称检查。
对于某些应用程序（主要是Web浏览器），由于“未知密钥共享”攻击，禁用名称检查是
不安全的，恶意服务器可以说服客户端与受害者服务器的连接而不是与恶意服务器的安全
连接。 恶意服务器可能能够违反跨原始脚本限制。 因此，尽管RFC7671的文本，默认情
况下，对DANE-EE（3）TLSA记录启用名称检查，并且可以在安全的应用程序中禁用名称检查。
特别是，SMTP和XMPP客户端应该将此选项设置为SRV和MX记录，使远程域可以将客户端连接
重定向到所选的任何服务器，无论如何，SMTP和XMPP客户端不会执行从远程服务器下载的脚本服务器。
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various certificate chain validation options. See the
L<verify(1)> manual page for details.
=item B<-reconnect>
reconnects to the same server 5 times using the same session ID, this can
be used as a test that session caching is working.
=item B<-pause>
pauses 1 second between each read and write call.
使用相同的会话ID重新连接到相同的服务器5次，这可以用作会话缓存正在工作的测试。
=item B<-showcerts>
display the whole server certificate chain: normally only the server
certificate itself is displayed.
显示整个服务器证书链：通常只显示服务器证书本身。
=item B<-prexit>
print session information when the program exits. This will always attempt
@@ -154,85 +361,199 @@ attempt is made to access a certain URL. Note: the output produced by this
option is not always accurate because a connection might never have been
established.
当程序退出时打印会话信息。 即使连接失败，它也将始终尝试打印出信息。 通常，
如果连接成功，信息将仅打印一次。 此选项非常有用，因为正在使用的密码可能被
重新协商，或连接可能会失败，因为客户端证书是必需的，或仅在尝试访问某个URL
后才被请求。 注意：此选项生成的输出并不总是准确的，因为连接可能永远不会建立。
=item B<-state>
prints out the SSL session states.
打印出SSL会话状态。
=item B<-debug>
print extensive debugging information including a hex dump of all traffic.
打印广泛的调试信息，包括所有流量的十六进制转储。
=item B<-msg>
show all protocol messages with hex dump.
显示所有具有十六进制转储的协议消息。
=item B<-trace>
show verbose trace output of protocol messages. GmSSL needs to be compiled
with B<enable-ssl-trace> for this option to work.
显示协议消息的详细跟踪输出。 需要使用enable-ssl-trace编译GmSSL才能使此选项生效。
=item B<-msgfile>
file to send output of B<-msg> or B<-trace> to, default standard output.
文件将-msg或-trace的输出发送到，默认标准输出。
=item B<-nbio_test>
tests non-blocking I/O
测试非阻塞I / O
=item B<-nbio>
turns on non-blocking I/O
打开非阻塞I / O
=item B<-crlf>
this option translated a line feed from the terminal into CR+LF as required
by some servers.
该选项根据某些服务器的要求将终端转换为CR + LF。
=item B<-ign_eof>
inhibit shutting down the connection when end of file is reached in the
input.
禁止在输入端到达文件结束时关闭连接。
=item B<-quiet>
inhibit printing of session and certificate information. This implicitly
turns on B<-ign_eof> as well.
禁止打印会话和证书信息。 这也隐含地打开-ign_eof。
=item B<-no_ign_eof>
shut down the connection when end of file is reached in the input.
Can be used to override the implicit B<-ign_eof> after B<-quiet>.
在输入端到达文件结束时关闭连接。 可以用于在-quiet之后覆盖隐式的-ign_eof。
=item B<-psk_identity identity>
Use the PSK identity B<identity> when using a PSK cipher suite.
The default value is "Client_identity" (without the quotes).
使用PSK密码套件时使用PSK身份标识。
=item B<-psk key>
Use the PSK key B<key> when using a PSK cipher suite. The key is
given as a hexadecimal number without leading 0x, for example -psk
1a2b3c4d.
This option must be provided in order to use a PSK cipher.
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
使用PSK密码套件时，请使用PSK密钥。 密钥以十六进制数字的形式给出，不带前缀0x，例如-psk 1a2b3c4d。
=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
These options require or disable the use of the specified SSL or TLS protocols.
By default the initial handshake uses a I<version-flexible> method which will
negotiate the highest mutually supported protocol version.
By default B<s_client> will negotiate the highest mutually supported protocol
version.
When a specific TLS version is required, only that version will be offered to
and accepted from the server.
这些选项需要或禁止使用指定的SSL或TLS协议。 默认情况下，s_client将协商最高相互
支持的协议版本。 当需要特定的TLS版本时，只有该版本将被提供给服务器并从服务器接受。
=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
These options make B<s_client> use DTLS protocols instead of TLS.
With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version,
whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2
respectively.
这些选项使s_client使用DTLS协议而不是TLS。 使用-dtls，s_client将协商任何支持的
DTLS协议版本，而-dtls1和-dtls1_2将分别仅支持DTLS1.0和DTLS1.2。
=item B<-fallback_scsv>
Send TLS_FALLBACK_SCSV in the ClientHello.
在ClientHello中发送TLS_FALLBACK_SCSV。
=item B<-async>
switch on asynchronous mode. Cryptographic operations will be performed
asynchronously. This will only have an effect if an asynchronous capable engine
is also used via the B<-engine> option. For test purposes the dummy async engine
(dasync) can be used (if available).
开启异步模式。 加密操作将被异步执行。 只有通过-engine选项也可以使用异步的引擎，
这只会产生影响。 为了测试目的，可以使用虚拟异步引擎（dasync）（如果可用）。
=item B<-split_send_frag int>
The size used to split data for encrypt pipelines. If more data is written in
one go than this value then it will be split into multiple pipelines, up to the
maximum number of pipelines defined by max_pipelines. This only has an effect if
a suitable ciphersuite has been negotiated, an engine that supports pipelining
has been loaded, and max_pipelines is greater than 1. See
L<SSL_CTX_set_split_send_fragment(3)> for further information.
用于分割加密管道数据的大小。 如果一次写入的数据多于此值，那么它将被分割成多个管道，
直到max_pipelines定义的最大管道数。 如果已经协商了合适的密码套件，则支持流水线的
引擎已被加载，并且max_pipelines大于1.请参阅SSL_CTX_set_split_send_fragment（3）
以获取更多信息。
=item B<-max_pipelines int>
The maximum number of encrypt/decrypt pipelines to be used. This will only have
an effect if an engine has been loaded that supports pipelining (e.g. the dasync
engine) and a suitable ciphersuite has been negotiated. The default value is 1.
See L<SSL_CTX_set_max_pipelines(3)> for further information.
要使用的加密/解密管道的最大数量。 如果已经加载支持流水线的引擎（例如，dasync引擎）
并且已经协商了合适的密码套件，则这将仅起作用。 默认值为1.有关更多信息，请参阅
SSL_CTX_set_max_pipelines（3）。
=item B<-read_buf int>
The default read buffer size to be used for connections. This will only have an
effect if the buffer size is larger than the size that would otherwise be used
and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
further information).
用于连接的默认读缓冲区大小。 如果缓冲区大小大于使用的流水线大小（如果需要进一步的信息，
请参阅SSL_CTX_set_default_read_buffer_len（3）），这只会产生影响。
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-sigalgs sigalglist>
SSL和TLS实现中有几个已知的错误。 添加此选项可以启用各种解决方法。
Specifies the list of signature algorithms that are sent by the client.
The server selects one entry in the list based on its preferences.
For example strings, see L<SSL_CTX_set1_sigalgs(3)>
=item B<-comp>
=item B<-curves curvelist>
Enables support for SSL/TLS compression.
This option was introduced in GmSSL 1.1.0.
TLS compression is not recommended and is off by default as of
GmSSL 1.1.0.
Specifies the list of supported curves to be sent by the client. The curve is
is ultimately selected by the server. For a list of all curves, use:
支持SSL / TLS压缩。 此选项在GmSSL 1.1.0中引入。 不推荐使用TLS压缩，
默认情况下，GmSSL 1.1.0关闭。
$ openssl ecparam -list_curves
=item B<-no_comp>
Disables support for SSL/TLS compression.
TLS compression is not recommended and is off by default as of
GmSSL 1.1.0.
禁用对SSL / TLS压缩的支持。 不推荐使用TLS压缩，默认情况下，GmSSL 1.1.0关闭。
=item B<-brief>
only provide a brief summary of connection parameters instead of the
normal verbose output.
只提供连接参数的简要摘要，而不是正常的详细输出。
=item B<-cipher cipherlist>
@@ -241,33 +562,54 @@ the server determines which cipher suite is used it should take the first
supported cipher in the list sent by the client. See the B<ciphers>
command for more information.
=item B<-serverpref>
use the server's cipher preferences; only used for SSLV2.
这允许客户端发送的密码列表被修改。 虽然服务器确定使用哪个密码套件，
但它应该在客户端发送的列表中使用第一个支持的密码。 有关详细信息，请参阅ciphers命令。
=item B<-starttls protocol>
send the protocol-specific message(s) to switch to TLS for communication.
B<protocol> is a keyword for the intended protocol. Currently, the only
supported keywords are "smtp", "pop3", "imap", and "ftp".
supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server",
and "irc."
发送特定于协议的消息切换到TLS进行通信。 协议是目标协议的关键字。 目前，
唯一支持的关键字是“smtp”，“pop3”，“imap”，“ftp”，“xmpp”，“xmpp-server”和“irc”。
=item B<-xmpphost hostname>
This option, when used with "-starttls xmpp" or "-starttls xmpp-server",
specifies the host for the "to" attribute of the stream element.
If this option is not specified, then the host specified with "-connect"
will be used.
此选项与“-starttls xmpp”或“-starttls xmpp-server”一起使用时，指定流元素
“to”属性的主机。 如果未指定此选项，则将使用“-connect”指定的主机。
=item B<-tlsextdebug>
print out a hex dump of any TLS extensions received from the server.
打印从服务器接收的任何TLS扩展的十六进制转储。
=item B<-no_ticket>
disable RFC4507bis session ticket support.
disable RFC4507bis session ticket support.
禁用RFC4507bis会话票证支持。
=item B<-sess_out filename>
output SSL session to B<filename>
输出SSL会话到filename
=item B<-sess_in sess.pem>
load SSL session from B<filename>. The client will attempt to resume a
connection from this session.
从filename加载SSL会话。 客户端将尝试从此会话恢复连接。
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<s_client>
@@ -275,26 +617,34 @@ 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.
指定引擎（通过其唯一的id字符串）将导致s_client尝试获取对指定引擎的功能引用，从而在需要时对其进行初始化。 然后，引擎将被设置为所有可用算法的默认值。
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
包含用于种子随机数生成器或EGD套接字的随机数据的文件或文件（参见RAND_egd（3））。 多个文件可以由与操作系统相关的字符分隔。 分离器是 对于MS-Windows，对于OpenVMS，以及：对于所有其他。
=item B<-serverinfo types>
a list of comma-separated TLS Extension Types (numbers between 0 and
a list of comma-separated TLS Extension Types (numbers between 0 and
65535). Each type will be sent as an empty ClientHello TLS Extension.
The server's response (if any) will be encoded and displayed as a PEM
file.
逗号分隔的TLS扩展类型列表（0到65535之间的数字）。 每个类型将作为一个空的ClientHello TLS扩展发送。 服务器的响应（如果有）将被编码并显示为PEM文件。
=item B<-status>
sends a certificate status request to the server (OCSP stapling). The server
response (if any) is printed out.
向服务器发送证书状态请求（OCSP装订）。 打印出服务器响应（如果有）。
=item B<-alpn protocols>, B<-nextprotoneg protocols>
these flags enable the
@@ -308,7 +658,30 @@ Protocol names are printable ASCII strings, for example "http/1.1" or
"spdy/3".
Empty list of protocols is treated specially and will cause the client to
advertise support for the TLS extension but disconnect just after
reciving ServerHello with a list of server supported protocols.
receiving ServerHello with a list of server supported protocols.
这些标志分别启用启用应用层协议协商协议或下一协议协议扩展。 ALPN是IETF标准，替代NPN。 协议列表是客户端应该广告支持的逗号分隔的协议名称。 该列表应该包含最需要的协议。 协议名称是可打印的ASCII字符串，例如“http / 1.1”或“spdy / 3”。 协议的空列表被特别处理，并且将导致客户端向TLS扩展发布支持，但是在使用服务器支持的协议列表接收ServerHello之后断开连接。
=item B<-ct|noct>
Use one of these two options to control whether Certificate Transparency (CT)
is enabled (B<-ct>) or disabled (B<-noct>).
If CT is enabled, signed certificate timestamps (SCTs) will be requested from
the server and reported at handshake completion.
Enabling CT also enables OCSP stapling, as this is one possible delivery method
for SCTs.
使用这两个选项之一来控制是否启用证书透明度（CT）或禁用（-noct）。 如果启用CT，将从服务器请求签名的证书时间戳（SCT），并在握手完成时报告。
启用CT还可以实现OCSP装订，因为这是SCT的一种可能的传送方式。
=item B<-ctlogfile>
A file containing a list of known Certificate Transparency logs. See
L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format.
包含已知证书透明度日志列表的文件。 有关预期的文件格式，请参阅SSL_CTX_set_ctlog_list_file（3）。
=back
@@ -326,16 +699,16 @@ connection will be closed down.
B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP
server the command:
openssl s_client -connect servername:443
gmssl s_client -connect servername:443
would typically be used (https uses port 443). If the connection succeeds
then an HTTP command can be given such as "GET /" to retrieve a web page.
If the handshake fails then there are several possible causes, if it is
nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> options can be tried
nothing obvious like no client certificate then the B<-bugs>,
B<-ssl3>, B<-tls1>, B<-no_ssl3>, B<-no_tls1> options can be tried
in case it is a buggy server. In particular you should play with these
options B<before> submitting a bug report to an OpenSSL mailing list.
options B<before> submitting a bug report to an GmSSL mailing list.
A frequent problem when attempting to get client certificates working
is that a web client complains it has no certificates or gives an empty
@@ -355,10 +728,6 @@ on the command line is no guarantee that the certificate works.
If there are problems verifying a server certificate then the
B<-showcerts> option can be used to show the whole chain.
Since the SSLv23 client hello cannot include compression methods or extensions
these will only be supported if its use is disabled, for example by using the
B<-no_sslv2> option.
The B<s_client> utility is a test tool and is designed to continue the
handshake after any certificate verification errors. As a result it will
accept any certificate chain (trusted or not) sent by the peer. None test
@@ -368,20 +737,30 @@ option: any verify errors are then returned aborting the handshake.
=head1 BUGS
Because this program has a lot of options and also because some of
the techniques used are rather old, the C source of s_client is rather
hard to read and not a model of how things should be done. A typical
SSL client program would be much simpler.
Because this program has a lot of options and also because some of the
techniques used are rather old, the C source of B<s_client> is rather hard to
read and not a model of how things should be done.
A typical SSL client program would be much simpler.
The B<-prexit> option is a bit of a hack. We should really report
information whenever a session is renegotiated.
=head1 SEE ALSO
L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
L<SSL_CONF_cmd(3)>,
L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to GmSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

493
doc/apps/s_server.pod
View File

@@ -1,14 +1,22 @@
=pod
=encoding utf8
=head1 NAME
s_server - SSL/TLS server program
=head1 SYNOPSIS
B<openssl> B<s_server>
[B<-accept port>]
B<gmssl> B<s_server>
[B<-help>]
[B<-port port>]
[B<-accept val>]
[B<-naccept count>]
[B<-unix val>]
[B<-unlink>]
[B<-4>]
[B<-6>]
[B<-context id>]
[B<-verify depth>]
[B<-Verify depth>]
@@ -33,23 +41,62 @@ B<openssl> B<s_server>
[B<-state>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_return_error>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-nocert>]
[B<-client_sigalgs sigalglist>]
[B<-named_curve curve>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-quiet>]
[B<-no_tmp_rsa>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-no_ssl2>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-tls1_3>]
[B<-dtls>]
[B<-dtls1>]
[B<-dtls1_2>]
[B<-listen>]
[B<-async>]
[B<-split_send_frag>]
[B<-max_pipelines>]
[B<-read_buf>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-no_tls1_3>]
[B<-no_dhe>]
[B<-bugs>]
[B<-hack>]
[B<-comp>]
[B<-no_comp>]
[B<-brief>]
[B<-www>]
[B<-WWW>]
[B<-HTTP>]
@@ -72,19 +119,75 @@ B<openssl> B<s_server>
The B<s_server> command implements a generic SSL/TLS server which listens
for connections on a given port using SSL/TLS.
s_server命令实现一个通用SSL / TLS服务器，它使用SSL / TLS监听给定端口上的连接。
=head1 OPTIONS
In addition to the options below the B<s_server> utility also supports the
common and server only options documented in the
in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
manual page.
除了以下选项之外，s_server实用程序还支持SSL_CONF_cmd（3）手册页的“支持的
命令行命令”部分中记录的通用和仅服务器选项。
=over 4
=item B<-accept port>
=item B<-help>
the TCP port to listen on for connections. If not specified 4433 is used.
Print out a usage message.
打印使用信息。
=item B<-port port>
The TCP port to listen on for connections. If not specified 4433 is used.
TCP端口监听连接。 如果未指定4433。
=item B<-accept val>
The optional TCP host and port to listen on for connections. If not specified, *:4433 is used.
可选的TCP主机和端口监听连接。 如果未指定，则使用*：4433。
=item B<-naccept count>
The server will exit after receiving B<number> connections, default unlimited.
收到number后，服务器将退出，默认为无限制。
=item B<-unix val>
Unix domain socket to accept on.
Unix域套接字接受。
=item B<-unlink>
For -unix, unlink existing socket first.
对于-unix，首先取消链接现有套接字。
=item B<-4>
Use IPv4 only.
只用IPv4
=item B<-6>
Use IPv6 only.
只用IPv6
=item B<-context id>
sets the SSL context id. It can be given any string value. If this option
Sets the SSL context id. It can be given any string value. If this option
is not present a default value will be used.
设置SSL上下文id。 可以给出任何字符串值。 如果此选项不存在，将使用默认值。
=item B<-cert certname>
The certificate to use, most servers cipher suites require the use of a
@@ -92,27 +195,37 @@ certificate and some require a certificate with a certain public key type:
for example the DSS cipher suites require a certificate containing a DSS
(DSA) key. If not specified then the filename "server.pem" will be used.
要使用的证书，大多数服务器密码套件需要使用证书，有些需要具有某种公钥类型的证书：例如，DSS密码套件需要包含DSS（DSA）密钥的证书。 如果未指定，则将使用文件名“server.pem”。
=item B<-certform format>
The certificate format to use: DER or PEM. PEM is the default.
使用的证书格式：DER或PEM。 PEM是默认值。
=item B<-key keyfile>
The private key to use. If not specified then the certificate file will
be used.
使用私钥。 如果未指定，则将使用证书文件。
=item B<-keyform format>
The private format to use: DER or PEM. PEM is the default.
要使用的私有格式：DER或PEM。 PEM是默认值。
=item B<-pass arg>
the private 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)>.
The private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
私钥密码源。 有关arg格式的更多信息，请参阅gmssl（1）中的PASS PHRASE ARGUMENTS部分。
=item B<-dcert filename>, B<-dkey keyname>
specify an additional certificate and private key, these behave in the
Specify an additional certificate and private key, these behave in the
same manner as the B<-cert> and B<-key> options except there is no default
if they are not specified (no additional certificate and key is used). As
noted above some cipher suites require a certificate containing a key of
@@ -121,32 +234,75 @@ and some a DSS (DSA) key. By using RSA and DSS certificates and keys
a server can support clients which only support RSA or DSS cipher suites
by using an appropriate certificate.
指定一个额外的证书和私钥，它们的行为方式与-cert和-key选项相同，除非没有指定默认值（不使用其他证书和密钥）。 如上所述，一些密码套件需要包含特定类型的密钥的证书。 一些密码套件需要携带RSA密钥的证书和一些DSS密钥。 通过使用RSA和DSS证书和密钥，服务器可以通过使用适当的证书来支持只支持RSA或DSS密码套件的客户端。
=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
additional certificate and private key format and passphrase respectively.
Additional certificate and private key format and passphrase respectively.
分别附加证书和私钥格式和密码。
=item B<-nocert>
if this option is set then no certificate is used. This restricts the
If this option is set then no certificate is used. This restricts the
cipher suites available to the anonymous ones (currently just anonymous
DH).
如果设置了此选项，则不会使用任何证书。 这限制了匿名的密码套件（目前只是匿名的DH）。
=item B<-dhparam filename>
the DH parameter file to use. The ephemeral DH cipher suites generate keys
The DH parameter file to use. The ephemeral DH cipher suites generate keys
using a set of DH parameters. If not specified then an attempt is made to
load the parameters from the server certificate file. If this fails then
a static set of parameters hard coded into the s_server program will be used.
load the parameters from the server certificate file.
If this fails then a static set of parameters hard coded into the B<s_server>
program will be used.
要使用的DH参数文件。 短时DH密码套件使用一组DH参数生成密钥。 如果未指定，则尝试从服务器证书文件加载参数。 如果失败，则将使用硬编码到s_server程序中的一组静态参数。
=item B<-no_dhe>
if this option is set then no DH parameters will be loaded effectively
If this option is set then no DH parameters will be loaded effectively
disabling the ephemeral DH cipher suites.
=item B<-no_tmp_rsa>
如果设置了此选项，则不会有效地加载DH参数，禁用临时DH密码套件。
certain export cipher suites sometimes use a temporary RSA key, this option
disables temporary RSA key generation.
=item B<-crl_check>, B<-crl_check_all>
Check the peer certificate has not been revoked by its CA.
The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
option all CRLs of all CAs in the chain are checked.
检查对等证书尚未被其CA撤销。 证书文件附加CRL。 使用-crl_check_all选项，将检查链中所有CA的所有CRL。
=item B<-CApath directory>
The directory to use for client certificate verification. This directory
must be in "hash format", see B<verify> for more information. These are
also used when building the server certificate chain.
用于客户端证书验证的目录。 此目录必须为“哈希格式”，请参阅验证更多信息。 这些也在构建服务器证书链时使用
=item B<-CAfile file>
A file containing trusted certificates to use during client authentication
and to use when attempting to build the server certificate chain. The list
is also used in the list of acceptable client CAs passed to the client when
a certificate is requested.
包含在客户端身份验证期间使用并在尝试构建服务器证书链时使用的可信证书的文件。 该列表也用于在请求证书时传递给客户端的可接受的客户端CA列表。
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
不要从默认文件位置加载受信任的CA证书
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
不要从默认目录位置加载受信任的CA证书
=item B<-verify depth>, B<-Verify depth>
@@ -159,190 +315,333 @@ must supply a certificate or an error occurs.
If the ciphersuite cannot request a client certificate (for example an
anonymous ciphersuite or PSK) this option has no effect.
=item B<-crl_check>, B<-crl_check_all>
验证使用深度。 这指定客户端证书链的最大长度，并使服务器从客户端请求证书。 使用-verify选项，请求证书，但客户端不必发送一个，使用-Verify选项，客户端必须提供证书或发生错误。
Check the peer certificate has not been revoked by its CA.
The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
option all CRLs of all CAs in the chain are checked.
如果密码不能请求客户端证书（例如匿名密码套件或PSK），则此选项不起作用。
=item B<-CApath directory>
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
The directory to use for client certificate verification. This directory
must be in "hash format", see B<verify> for more information. These are
also used when building the server certificate chain.
Set different peer certificate verification options.
See the L<verify(1)> manual page for details.
=item B<-CAfile file>
设置不同的对等证书验证选项。 有关详细信息，请参阅verify（1）手册页。
A file containing trusted certificates to use during client authentication
and to use when attempting to build the server certificate chain. The list
is also used in the list of acceptable client CAs passed to the client when
a certificate is requested.
=item B<-verify_return_error>
=item B<-no_alt_chains>
Verification errors normally just print a message but allow the
connection to continue, for debugging purposes.
If this option is used, then verification errors close the connection.
See the L<B<verify>|verify(1)> manual page for details.
验证错误通常只是打印一条消息，但允许连接继续进行调试。 如果使用此选项，则验证错误会关闭连接。
=item B<-state>
prints out the SSL session states.
Prints the SSL session states.
打印SSL会话状态。
=item B<-debug>
print extensive debugging information including a hex dump of all traffic.
Print extensive debugging information including a hex dump of all traffic.
打印广泛的调试信息，包括所有流量的十六进制转储。
=item B<-msg>
show all protocol messages with hex dump.
Show all protocol messages with hex dump.
使用十六进制转储显示所有协议消息。
=item B<-trace>
Show verbose trace output of protocol messages. GmSSL needs to be compiled
with B<enable-ssl-trace> for this option to work.
显示协议消息的详细跟踪输出。 需要使用enable-ssl-trace编译GmSSL才能使此选项生效。
=item B<-msgfile>
File to send output of B<-msg> or B<-trace> to, default standard output.
文件将-msg或-trace的输出发送到，默认标准输出。
=item B<-nbio_test>
tests non blocking I/O
Tests non blocking I/O
测试非阻塞I / O
=item B<-nbio>
turns on non blocking I/O
Turns on non blocking I/O
打开非阻塞I / O
=item B<-crlf>
this option translated a line feed from the terminal into CR+LF.
This option translated a line feed from the terminal into CR+LF.
此选项将换行符从终端转换为CR + LF。
=item B<-quiet>
inhibit printing of session and certificate information.
Inhibit printing of session and certificate information.
禁止打印会话和证书信息。
=item B<-psk_hint hint>
Use the PSK identity hint B<hint> when using a PSK cipher suite.
使用PSK密码套件时，请使用PSK身份提示提示。
=item B<-psk key>
Use the PSK key B<key> when using a PSK cipher suite. The key is
given as a hexadecimal number without leading 0x, for example -psk
1a2b3c4d.
This option must be provided in order to use a PSK cipher.
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
使用PSK密码套件时，请使用PSK密钥。 密钥以十六进制数字的形式给出，不带前缀0x，例如-psk 1a2b3c4d。
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-tls1_3>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>, B<-no_tls1_3>
These options require or disable the use of the specified SSL or TLS protocols.
By default the initial handshake uses a I<version-flexible> method which will
negotiate the highest mutually supported protocol version.
By default B<s_server> will negotiate the highest mutually supported protocol
version.
When a specific TLS version is required, only that version will be accepted
from the client.
这些选项需要或禁止使用指定的SSL或TLS协议。 默认情况下，s_server将协商最高相互支持的协议版本。 当需要特定的TLS版本时，只有客户端才接受该版本。
=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
These options make B<s_server> use DTLS protocols instead of TLS.
With B<-dtls>, B<s_server> will negotiate any supported DTLS protocol version,
whilst B<-dtls1> and B<-dtls1_2> will only support DTLSv1.0 and DTLSv1.2
respectively.
这些选项使s_server使用DTLS协议而不是TLS。 使用-dtls，s_server将协商任何支持的DTLS协议版本，而-dtls1和-dtls1_2将分别仅支持DTLSv1.0和DTLSv1.2。
=item B<-listen>
This option can only be used in conjunction with one of the DTLS options above.
With this option B<s_server> will listen on a UDP port for incoming connections.
Any ClientHellos that arrive will be checked to see if they have a cookie in
them or not.
Any without a cookie will be responded to with a HelloVerifyRequest.
If a ClientHello with a cookie is received then B<s_server> will connect to
that peer and complete the handshake.
此选项只能与上述DTLS选项结合使用。 使用此选项，s_server将在UDP端口上侦听传入连接。 任何到达的ClientHellos将被检查，看看他们是否有cookie。 任何没有cookie的人都会通过一个HelloVerifyRequest进行回复。 如果接收到具有cookie的ClientHello，则s_server将连接到该对等体并完成握手。
=item B<-async>
Switch on asynchronous mode. Cryptographic operations will be performed
asynchronously. This will only have an effect if an asynchronous capable engine
is also used via the B<-engine> option. For test purposes the dummy async engine
(dasync) can be used (if available).
打开异步模式。 加密操作将被异步执行。 只有通过-engine选项也可以使用异步的引擎，这只会产生影响。 为了测试目的，可以使用虚拟异步引擎（dasync）（如果可用）。
=item B<-split_send_frag int>
The size used to split data for encrypt pipelines. If more data is written in
one go than this value then it will be split into multiple pipelines, up to the
maximum number of pipelines defined by max_pipelines. This only has an effect if
a suitable ciphersuite has been negotiated, an engine that supports pipelining
has been loaded, and max_pipelines is greater than 1. See
L<SSL_CTX_set_split_send_fragment(3)> for further information.
用于分割加密管道数据的大小。 如果一次写入的数据多于此值，那么它将被分割成多个管道，直到max_pipelines定义的最大管道数。 如果已经协商了合适的密码套件，则支持流水线的引擎已被加载，并且max_pipelines大于1.请参阅SSL_CTX_set_split_send_fragment（3）以获取更多信息。
=item B<-max_pipelines int>
The maximum number of encrypt/decrypt pipelines to be used. This will only have
an effect if an engine has been loaded that supports pipelining (e.g. the dasync
engine) and a suitable ciphersuite has been negotiated. The default value is 1.
See L<SSL_CTX_set_max_pipelines(3)> for further information.
要使用的加密/解密管道的最大数量。 如果已经加载支持流水线的引擎（例如，dasync引擎）并且已经协商了合适的密码套件，则这将仅起作用。 默认值为1.有关更多信息，请参阅SSL_CTX_set_max_pipelines（3）。
=item B<-read_buf int>
The default read buffer size to be used for connections. This will only have an
effect if the buffer size is larger than the size that would otherwise be used
and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
further information).
用于连接的默认读缓冲区大小。 如果缓冲区大小大于使用的流水线大小（如果需要进一步的信息，请参阅SSL_CTX_set_default_read_buffer_len（3）），这只会产生影响。
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
There are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-hack>
SSL和TLS实现中有几个已知的错误。 添加此选项可以启用各种解决方法。
this option enables a further workaround for some some early Netscape
SSL code (?).
=item B<-comp>
=item B<-client_sigalgs sigalglist>
Enable negotiation of TLS compression.
This option was introduced in GmSSL 1.1.0.
TLS compression is not recommended and is off by default as of
GmSSL 1.1.0.
Signature algorithms to support for client certificate authentication
(colon-separated list)
启用TLS压缩协商。 此选项在GmSSL 1.1.0中引入。 不推荐使用TLS压缩，默认情况下，GmSSL 1.1.0关闭。
=item B<-named_curve curve>
=item B<-no_comp>
Specifies the elliptic curve to use. NOTE: this is single curve, not a list.
For a list of all possible curves, use:
Disable negotiation of TLS compression.
TLS compression is not recommended and is off by default as of
GmSSL 1.1.0.
$ openssl ecparam -list_curves
禁用TLS压缩协商。 不推荐使用TLS压缩，默认情况下，GmSSL 1.1.0关闭。
=item B<-brief>
Provide a brief summary of connection parameters instead of the normal verbose
output.
提供连接参数的简要摘要，而不是正常的详细输出。
=item B<-cipher cipherlist>
this allows the cipher list used by the server to be modified. When
This allows the cipher list used by the server to be modified. When
the client sends a list of supported ciphers the first client cipher
also included in the server list is used. Because the client specifies
the preference order, the order of the server cipherlist irrelevant. See
the B<ciphers> command for more information.
这样可以修改服务器使用的密码列表。 当客户端发送支持的密码列表时，也使用包含在服务器列表中的第一个客户端密码。 因为客户端指定了优先级顺序，所以服务器密码列表的顺序不相关。 有关详细信息，请参阅ciphers命令。
=item B<-serverpref>
use the server's cipher preferences, rather than the client's preferences.
Use the server's cipher preferences, rather than the client's preferences.
使用服务器的密码首选项，而不是客户端的首选项。
=item B<-tlsextdebug>
print out a hex dump of any TLS extensions received from the server.
Print a hex dump of any TLS extensions received from the server.
打印从服务器接收的任何TLS扩展的十六进制转储。
=item B<-no_ticket>
disable RFC4507bis session ticket support.
Disable RFC4507bis session ticket support.
禁用RFC4507bis会话票证支持。
=item B<-www>
sends a status message back to the client when it connects. This includes
lots of information about the ciphers used and various session parameters.
Sends a status message back to the client when it connects. This includes
information about the ciphers used and various session parameters.
The output is in HTML format so this option will normally be used with a
web browser.
当连接时，向客户端发送状态消息。 这包括有关使用的密码和各种会话参数的信息。 输出是HTML格式，因此这个选项通常与网络浏览器一起使用。
=item B<-WWW>
emulates a simple web server. Pages will be resolved relative to the
Emulates a simple web server. Pages will be resolved relative to the
current directory, for example if the URL https://myhost/page.html is
requested the file ./page.html will be loaded.
模拟一个简单的Web服务器。 页面将相对于当前目录进行解析，例如，如果URL https：//myhost/page.html被请求，将加载./page.html文件。
=item B<-HTTP>
emulates a simple web server. Pages will be resolved relative to the
Emulates a simple web server. Pages will be resolved relative to the
current directory, for example if the URL https://myhost/page.html is
requested the file ./page.html will be loaded. The files loaded are
assumed to contain a complete and correct HTTP response (lines that
are part of the HTTP response line and headers must end with CRLF).
模拟一个简单的Web服务器。 页面将相对于当前目录进行解析，例如，如果URL https：//myhost/page.html被请求，将加载./page.html文件。 假设加载的文件包含完整且正确的HTTP响应（作为HTTP响应行的一部分的行，头必须以CRLF结尾）。
=item B<-rev>
Simple test server which just reverses the text received from the client
and sends it back to the server. Also sets B<-brief>.
简单的测试服务器，只是反转从客户端收到的文本并将其发送回服务器。 还设置-brief。
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<s_server>
Specifying an engine (by its unique B<id> string) will cause B<s_server>
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.
指定引擎（通过其唯一的id字符串）将导致s_server尝试获取对指定引擎的功能引用，从而在需要时对其进行初始化。 然后，引擎将被设置为所有可用算法的默认值。
=item B<-id_prefix arg>
generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
Generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
servers, when each of which might be generating a unique range of session
IDs (eg. with a certain prefix).
生成以arg为前缀的SSL / TLS会话ID。 这主要用于测试希望处理多个服务器的任何SSL / TLS代码（例如代理），当每个服务器可能会生成唯一的会话ID范围（例如，具有特定前缀）时。
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
A file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
包含用于种子随机数生成器或EGD套接字的随机数据的文件或文件（参见RAND_egd（3））。 多个文件可以由与操作系统相关的字符分隔。 分离器是 对于MS-Windows，对于OpenVMS，以及：对于所有其他。
=item B<-serverinfo file>
a file containing one or more blocks of PEM data. Each PEM block
A file containing one or more blocks of PEM data. Each PEM block
must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
followed by "length" bytes of extension data). If the client sends
an empty TLS ClientHello extension matching the type, the corresponding
ServerHello extension will be returned.
包含一个或多个PEM数据块的文件。 每个PEM块必须编码TLS ServerHello扩展（2字节类型，2字节长度，后跟扩展数据的“长度”字节）。 如果客户端发送与该类型相匹配的空TLS ClientHello扩展名，则将返回相应的ServerHello扩展名。
=item B<-no_resumption_on_reneg>
set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag.
Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option.
设置SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION选项。
=item B<-status>
enables certificate status request support (aka OCSP stapling).
Enables certificate status request support (aka OCSP stapling).
启用证书状态请求支持（也称为OCSP装订）。
=item B<-status_verbose>
enables certificate status request support (aka OCSP stapling) and gives
Enables certificate status request support (aka OCSP stapling) and gives
a verbose printout of the OCSP response.
启用证书状态请求支持（也称为OCSP装订），并给出OCSP响应的详细打印输出。
=item B<-status_timeout nsec>
sets the timeout for OCSP response to B<nsec> seconds.
Sets the timeout for OCSP response to B<nsec> seconds.
将OCSP响应的超时设置为nsec秒。
=item B<-status_url url>
sets a fallback responder URL to use if no responder URL is present in the
Sets a fallback responder URL to use if no responder URL is present in the
server certificate. Without this option an error is returned if the server
certificate does not contain a responder address.
如果服务器证书中没有响应者URL，则设置要使用的回退应答器URL。 没有此选项，如果服务器证书不包含响应者地址，则会返回错误。
=item B<-alpn protocols>, B<-nextprotoneg protocols>
these flags enable the
@@ -355,13 +654,15 @@ The list should contain most wanted protocols first.
Protocol names are printable ASCII strings, for example "http/1.1" or
"spdy/3".
这些标志分别启用启用应用层协议协商协议或下一协议协议扩展。 ALPN是IETF标准，替代NPN。 协议列表是支持的协议名称的逗号分隔列表。 该列表应该包含最需要的协议。 协议名称是可打印的ASCII字符串，例如“http / 1.1”或“spdy / 3”。
=back
=head1 CONNECTED COMMANDS
If a connection request is established with an SSL client and neither the
B<-www> nor the B<-WWW> option has been used then normally any data received
from the client is displayed and any key presses will be sent to the client.
from the client is displayed and any key presses will be sent to the client.
Certain single letter commands are also recognized which perform special
operations: these are listed below.
@@ -400,10 +701,14 @@ print out some session cache status information.
B<s_server> can be used to debug SSL clients. To accept connections from
a web browser the command:
openssl s_server -accept 443 -www
gmssl s_server -accept 443 -www
can be used for example.
Most web browsers (in particular Netscape and MSIE) only support RSA cipher
suites, so they cannot connect to servers which don't use a certificate
carrying an RSA key or a version of GmSSL with RSA disabled.
Although specifying an empty list of CAs when requesting a client certificate
is strictly speaking a protocol violation, some SSL clients interpret this to
mean any CA is acceptable. This is useful for debugging purposes.
@@ -412,23 +717,33 @@ The session parameters can printed out using the B<sess_id> program.
=head1 BUGS
Because this program has a lot of options and also because some of
the techniques used are rather old, the C source of s_server is rather
hard to read and not a model of how things should be done. A typical
SSL server program would be much simpler.
Because this program has a lot of options and also because some of the
techniques used are rather old, the C source of B<s_server> is rather hard to
read and not a model of how things should be done.
A typical SSL server program would be much simpler.
The output of common ciphers is wrong: it just gives the list of ciphers that
OpenSSL recognizes and the client supports.
GmSSL recognizes and the client supports.
There should be a way for the B<s_server> program to print out details of any
unknown cipher suites a client says it supports.
=head1 SEE ALSO
L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)>
L<SSL_CONF_cmd(3)>,
L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to GmSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

57
doc/apps/s_time.pod
View File

@@ -1,25 +1,28 @@
=pod
=encoding utf8
=head1 NAME
s_time - SSL/TLS performance timing program
=head1 SYNOPSIS
B<openssl> B<s_time>
B<gmssl> B<s_time>
[B<-help>]
[B<-connect host:port>]
[B<-www page>]
[B<-cert filename>]
[B<-key filename>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-reuse>]
[B<-new>]
[B<-verify depth>]
[B<-nbio>]
[B<-time seconds>]
[B<-ssl2>]
[B<-ssl3>]
[B<-bugs>]
[B<-cipher cipherlist>]
@@ -36,6 +39,10 @@ transferred (if any), and calculates the average time spent for one connection.
=over 4
=item B<-help>
Print out a usage message.
=item B<-connect host:port>
This specifies the host and optional port to connect to.
@@ -76,6 +83,14 @@ 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<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-new>
performs the timing test using a new session ID for each connection.
@@ -92,18 +107,17 @@ specified, they are both on by default and executed in sequence.
turns on non-blocking I/O.
=item B<-ssl2>, B<-ssl3>
=item B<-ssl3>
these options disable the use of certain SSL or TLS protocols. By default
the initial handshake uses a method which should be compatible with all
servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
servers and permit them to use SSL v3 or TLS as appropriate.
The timing program is not as rich in options to turn protocols on and off as
the L<s_client(1)|s_client(1)> program and may not connect to all servers.
the L<s_client(1)> program and may not connect to all servers.
Unfortunately there are a lot of ancient and broken servers in use which
cannot handle this technique and will fail to connect. Some servers only
work if TLS is turned off with the B<-ssl3> option; others
will only support SSL v2 and may need the B<-ssl2> option.
work if TLS is turned off with the B<-ssl3> option.
=item B<-bugs>
@@ -115,7 +129,7 @@ option enables various workarounds.
this allows the cipher list sent by the client to be modified. Although
the server determines which cipher suite is used it should take the first
supported cipher in the list sent by the client.
See the L<ciphers(1)|ciphers(1)> command for more information.
See the L<ciphers(1)> command for more information.
=item B<-time length>
@@ -130,26 +144,26 @@ and the link speed determine how many connections B<s_time> can establish.
B<s_time> can be used to measure the performance of an SSL connection.
To connect to an SSL HTTP server and get the default page the command
openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
gmssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
would typically be used (https uses port 443). 'commoncipher' is a cipher to
which both client and server can agree, see the L<ciphers(1)|ciphers(1)> command
which both client and server can agree, see the L<ciphers(1)> command
for details.
If the handshake fails then there are several possible causes, if it is
nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
nothing obvious like no client certificate then the B<-bugs> and
B<-ssl3> options can be tried
in case it is a buggy server. In particular you should play with these
options B<before> submitting a bug report to an OpenSSL mailing list.
options B<before> submitting a bug report to an GmSSL mailing list.
A frequent problem when attempting to get client certificates working
is that a web client complains it has no certificates or gives an empty
list to choose from. This is normally because the server is not sending
the clients certificate authority in its "acceptable CA list" when it
requests a certificate. By using L<s_client(1)|s_client(1)> the CA list can be
requests a certificate. By using L<s_client(1)> the CA list can be
viewed and checked. However some servers only request client authentication
after a specific URL is requested. To obtain the list in this case it
is necessary to use the B<-prexit> option of L<s_client(1)|s_client(1)> and
is necessary to use the B<-prexit> option of L<s_client(1)> and
send an HTTP request for an appropriate page.
If a certificate is specified on the command line using the B<-cert>
@@ -160,7 +174,7 @@ on the command line is no guarantee that the certificate works.
=head1 BUGS
Because this program does not have all the options of the
L<s_client(1)|s_client(1)> program to turn protocols on and off, you may not be
L<s_client(1)> program to turn protocols on and off, you may not be
able to measure the performance of all protocols with all servers.
The B<-verify> option should really exit if the server verification
@@ -168,6 +182,15 @@ fails.
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
L<s_client(1)>, L<s_server(1)>, L<ciphers(1)>
=head1 COPYRIGHT
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

42
doc/apps/sess_id.pod
View File

@@ -1,15 +1,17 @@
=pod
=encoding utf8
=head1 NAME
sess_id - SSL/TLS session handling utility
=head1 SYNOPSIS
B<openssl> B<sess_id>
B<gmssl> B<sess_id>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-outform PEM|DER|NSS>]
[B<-in filename>]
[B<-out filename>]
[B<-text>]
@@ -24,8 +26,14 @@ master key) in human readable format. Since this is a diagnostic tool that
needs some knowledge of the SSL protocol to use properly, most users will
not need to use it.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -33,10 +41,11 @@ format containing session details. The precise format can vary from one version
to the next. The B<PEM> form is the default format: it consists of the B<DER>
format base64 encoded with additional header and footer lines.
=item B<-outform DER|PEM>
=item B<-outform DER|PEM|NSS>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
This specifies the output format. The B<PEM> and B<DER> options have the same meaning
as the B<-inform> option. The B<NSS> option outputs the session id and the master key
in NSS keylog format.
=item B<-in filename>
@@ -51,7 +60,7 @@ output if this option is not specified.
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
plain text in addition to the encoded version.
=item B<-cert>
@@ -65,7 +74,7 @@ this option prevents output of the encoded version of the session.
=item B<-context ID>
this option can set the session id so the output session information uses the
supplied ID. The ID can be any string of characters. This option wont normally
supplied ID. The ID can be any string of characters. This option won't normally
be used.
=back
@@ -91,7 +100,7 @@ Theses are described below in more detail.
=item B<Protocol>
this is the protocol in use TLSv1, SSLv3 or SSLv2.
this is the protocol in use TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
=item B<Cipher>
@@ -110,10 +119,6 @@ the session ID context in hex format.
this is the SSL session master key.
=item B<Key-Arg>
the key argument, this is only used in SSL v2.
=item B<Start Time>
this is the session start time represented as an integer in standard Unix format.
@@ -146,6 +151,15 @@ The cipher and start time should be printed out in human readable form.
=head1 SEE ALSO
L<ciphers(1)|ciphers(1)>, L<s_server(1)|s_server(1)>
L<ciphers(1)>, L<s_server(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

149
doc/apps/smime.pod
View File

@@ -1,21 +1,56 @@
=pod
=encoding utf8
=head1 NAME
smime - S/MIME utility
=head1 SYNOPSIS
B<openssl> B<smime>
B<gmssl> B<smime>
[B<-help>]
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
[B<-resign>]
[B<-verify>]
[B<-pk7out>]
[B<-binary>]
[B<-crlfeol>]
[B<-[cipher]>]
[B<-in file>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-certfile file>]
[B<-signer file>]
[B<-recip file>]
@@ -41,13 +76,17 @@ B<openssl> B<smime>
The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
verify S/MIME messages.
=head1 COMMAND OPTIONS
=head1 OPTIONS
There are six operation options that set the type of operation to be performed.
The meaning of the other options varies according to the operation type.
=over 4
=item B<-help>
Print out a usage message.
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
@@ -136,7 +175,7 @@ is S/MIME and it uses the multipart/signed MIME content type.
this option adds plain text (text/plain) MIME headers to the supplied
message if encrypting or signing. If decrypting or verifying it strips
off text headers: if the decrypted or verified message is not of MIME
off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
=item B<-CAfile file>
@@ -150,6 +189,14 @@ B<-verify>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
@@ -159,9 +206,9 @@ default digest algorithm for the signing key will be used (usually SHA1).
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>. See L<B<enc>|enc(1)> for list of ciphers
supported by your version of OpenSSL.
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers
supported by your version of GmSSL.
If not specified triple DES is used. Only used with B<-encrypt>.
@@ -205,6 +252,11 @@ effectively using CR and LF as end of line: as required by the S/MIME
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
=item B<-crlfeol>
normally the output file uses a single B<LF> as end of line. When this
option is present B<CRLF> is used instead.
=item B<-nodetach>
when signing a message use opaque signing: this form is more resistant
@@ -241,20 +293,20 @@ multiple times to specify successive keys.
=item B<-passin arg>
the private 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
one or more certificates of message recipients: used when encrypting
a message.
a message.
=item B<-to, -from, -subject>
@@ -263,10 +315,16 @@ 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 -check_ss_sig -no_alt_chains>
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various options of certificate chain verification. See
L<B<verify>|verify(1)> manual page for details.
L<verify(1)> manual page for details.
=back
@@ -278,7 +336,7 @@ a blank line. Piping the mail directly to sendmail is one way to
achieve the correct format.
The supplied message to be signed or encrypted must include the
necessary MIME headers or many S/MIME clients wont display it
necessary MIME headers or many S/MIME clients won't display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
@@ -299,7 +357,7 @@ The B<-resign> option uses an existing message digest when adding a new
signer. This means that attributes must be present in at least one existing
signer using the same message digest or this operation will fail.
The B<-stream> and B<-indef> options enable experimental streaming I/O support.
The B<-stream> and B<-indef> options enable streaming I/O support.
As a result the encoding is BER using indefinite length constructed encoding
and no longer DER. Streaming is supported for the B<-encrypt> operation and the
B<-sign> operation if the content is not detached.
@@ -344,54 +402,54 @@ the signers certificates.
Create a cleartext signed message:
openssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
gmssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
Create an opaque signed message:
openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
gmssl smime -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
Create a signed message, include some additional certificates and
read the private key from another file:
openssl smime -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
gmssl smime -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
Create a signed message with two signers:
openssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem
gmssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem
Send a signed message under Unix directly to sendmail, including headers:
openssl smime -sign -in in.txt -text -signer mycert.pem \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
gmssl smime -sign -in in.txt -text -signer mycert.pem \
-from steve@gmssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
gmssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
Send encrypted mail using triple DES:
openssl smime -encrypt -in in.txt -from steve@openssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
gmssl smime -encrypt -in in.txt -from steve@gmssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
Sign and encrypt mail:
openssl smime -sign -in ml.txt -signer my.pem -text \
| openssl smime -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
gmssl smime -sign -in ml.txt -signer my.pem -text \
| gmssl smime -encrypt -out mail.msg \
-from steve@gmssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
Decrypt mail:
openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
gmssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
The output from Netscape form signing is a PKCS#7 structure with the
detached signature format. You can use this program to verify the
@@ -401,21 +459,21 @@ it with:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command:
and using the command:
openssl smime -verify -inform PEM -in signature.pem -content content.txt
gmssl smime -verify -inform PEM -in signature.pem -content content.txt
Alternatively you can base64 decode the signature and use:
openssl smime -verify -inform DER -in signature.der -content content.txt
gmssl smime -verify -inform DER -in signature.der -content content.txt
Create an encrypted message using 128 bit Camellia:
openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
gmssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
Add a signer to an existing message:
openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg
gmssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg
=head1 BUGS
@@ -443,8 +501,17 @@ structures may cause parsing errors.
=head1 HISTORY
The use of multiple B<-signer> options and the B<-resign> command were first
added in OpenSSL 1.0.0
added in GmSSL 1.0.0
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to GmSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

76
doc/apps/speed.pod
View File

@@ -1,47 +1,39 @@
=pod
=encoding utf8
=head1 NAME
speed - test library performance
=head1 SYNOPSIS
B<openssl speed>
B<gmssl speed>
[B<-help>]
[B<-engine id>]
[B<md2>]
[B<mdc2>]
[B<md5>]
[B<hmac>]
[B<sha1>]
[B<rmd160>]
[B<idea-cbc>]
[B<rc2-cbc>]
[B<rc5-cbc>]
[B<bf-cbc>]
[B<des-cbc>]
[B<des-ede3>]
[B<rc4>]
[B<rsa512>]
[B<rsa1024>]
[B<rsa2048>]
[B<rsa4096>]
[B<dsa512>]
[B<dsa1024>]
[B<dsa2048>]
[B<idea>]
[B<rc2>]
[B<des>]
[B<rsa>]
[B<blowfish>]
[B<-elapsed>]
[B<-evp algo>]
[B<-decrypt>]
[B<algorithm...>]
=head1 DESCRIPTION
This command is used to test the performance of cryptographic algorithms.
To see the list of supported algorithms, use the I<list --digest-commands>
or I<list --cipher-commands> command.
此命令用于测试加密算法的性能。 要查看支持的算法列表，请使用list --digest-commands或list --cipher-commands命令。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
打印使用信息
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<speed>
@@ -49,11 +41,43 @@ 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.
指定引擎（通过其唯一的id字符串）将导致speed尝试获得对指定引擎的功能引用，从而在需要时初始化它。 然后，引擎将被设置为所有可用算法的默认值。
=item B<-elapsed>
Measure time in real time instead of CPU time. It can be useful when testing
speed of hardware engines.
实时测量时间，而不是CPU时间。 在测试硬件引擎的速度时可能会很有用。
=item B<-evp algo>
Use the specified cipher or message digest algorithm via the EVP interface.
通过EVP接口使用指定的密码或消息摘要算法。
=item B<-decrypt>
Time the decryption instead of encryption. Affects only the EVP testing.
时间解密而不是加密。 仅影响EVP测试。
=item B<[zero or more test algorithms]>
If any options are given, B<speed> tests those algorithms, otherwise all of
the above are tested.
如果有任何选项，speed测试这些算法，否则所有上述都被测试。
=back
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

30
doc/apps/spkac.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
spkac - SPKAC printing and generating utility
=head1 SYNOPSIS
B<openssl> B<spkac>
B<gmssl> B<spkac>
[B<-help>]
[B<-in filename>]
[B<-out filename>]
[B<-key keyfile>]
@@ -25,10 +28,14 @@ The B<spkac> command processes Netscape signed public key and challenge
(SPKAC) files. It can print out their contents, verify the signature and
produce its own SPKACs from a supplied private key.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read from or standard input if this
@@ -48,7 +55,7 @@ present.
=item B<-passin password>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
=item B<-challenge string>
@@ -92,15 +99,15 @@ for all available algorithms.
Print out the contents of an SPKAC:
openssl spkac -in spkac.cnf
gmssl spkac -in spkac.cnf
Verify the signature of an SPKAC:
openssl spkac -in spkac.cnf -noout -verify
gmssl spkac -in spkac.cnf -noout -verify
Create an SPKAC using the challenge string "hello":
openssl spkac -key key.pem -challenge hello -out spkac.cnf
gmssl spkac -key key.pem -challenge hello -out spkac.cnf
Example of an SPKAC, (long lines split up for clarity):
@@ -128,6 +135,15 @@ to be used in a "replay attack".
=head1 SEE ALSO
L<ca(1)|ca(1)>
L<ca(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

204
doc/apps/ts.pod
View File

@@ -1,26 +1,28 @@
=pod
=encoding utf8
=head1 NAME
ts - Time Stamping Authority tool (client/server)
=head1 SYNOPSIS
B<openssl> B<ts>
B<gmssl> B<ts>
B<-query>
[B<-rand> file:file...]
[B<-config> configfile]
[B<-data> file_to_hash]
[B<-digest> digest_bytes]
[B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>]
[B<-policy> object_id]
[B<-[digest]>]
[B<-tspolicy> object_id]
[B<-no_nonce>]
[B<-cert>]
[B<-in> request.tsq]
[B<-out> request.tsq]
[B<-text>]
B<openssl> B<ts>
B<gmssl> B<ts>
B<-reply>
[B<-config> configfile]
[B<-section> tsa_section]
@@ -28,8 +30,9 @@ B<-reply>
[B<-passin> password_src]
[B<-signer> tsa_cert.pem]
[B<-inkey> private.pem]
[B<-sha1|-sha224|-sha256|-sha384|-sha512>]
[B<-chain> certs_file.pem]
[B<-policy> object_id]
[B<-tspolicy> object_id]
[B<-in> response.tsr]
[B<-token_in>]
[B<-out> response.tsr]
@@ -37,7 +40,7 @@ B<-reply>
[B<-text>]
[B<-engine> id]
B<openssl> B<ts>
B<gmssl> B<ts>
B<-verify>
[B<-data> file_to_hash]
[B<-digest> digest_bytes]
@@ -47,6 +50,38 @@ B<-verify>
[B<-CApath> trusted_cert_path]
[B<-CAfile> trusted_certs.pem]
[B<-untrusted> cert_file.pem]
[I<verify options>]
I<verify options:>
[-attime timestamp]
[-check_ss_sig]
[-crl_check]
[-crl_check_all]
[-explicit_policy]
[-extended_crl]
[-ignore_critical]
[-inhibit_any]
[-inhibit_map]
[-issuer_checks]
[-no_alt_chains]
[-no_check_time]
[-partial_chain]
[-policy arg]
[-policy_check]
[-policy_print]
[-purpose purpose]
[-suiteB_128]
[-suiteB_128_only]
[-suiteB_192]
[-trusted_first]
[-use_deltas]
[-auth_level num]
[-verify_depth num]
[-verify_email email]
[-verify_hostname hostname]
[-verify_ip ip]
[-verify_name name]
[-x509_strict]
=head1 DESCRIPTION
@@ -121,16 +156,16 @@ parameter is specified. (Optional)
It is possible to specify the message imprint explicitly without the data
file. The imprint must be specified in a hexadecimal format, two characters
per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
1AF601...). The number of bytes must match the message digest algorithm
1AF601...). The number of bytes must match the message digest algorithm
in use. (Optional)
=item B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>
=item B<-[digest]>
The message digest to apply to the data file, it supports all the message
digest algorithms that are supported by the openssl B<dgst> command.
The message digest to apply to the data file.
Any digest supported by the GmSSL B<dgst> command can be used.
The default is SHA-1. (Optional)
=item B<-policy> object_id
=item B<-tspolicy> object_id
The policy that the client expects the TSA to use for creating the
time stamp token. Either the dotted OID notation or OID names defined
@@ -189,7 +224,7 @@ OPTIONS> for configurable variables. (Optional)
=item B<-section> tsa_section
The name of the config file section conatining the settings for the
The name of the config file section containing the settings for the
response generation. If not specified the default TSA section is
used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional)
@@ -200,7 +235,7 @@ The name of the file containing a DER encoded time stamp request. (Optional)
=item B<-passin> password_src
Specifies the password source for the private key of the TSA. See
B<PASS PHRASE ARGUMENTS> in L<openssl(1)|openssl(1)>. (Optional)
B<PASS PHRASE ARGUMENTS> in L<gmssl(1)>. (Optional)
=item B<-signer> tsa_cert.pem
@@ -215,6 +250,11 @@ variable of the config file. (Optional)
The signer private key of the TSA in PEM format. Overrides the
B<signer_key> config file option. (Optional)
=item B<-sha1|-sha224|-sha256|-sha384|-sha512>
Signing digest to use. Overrides the B<signer_digest> config file
option. (Optional)
=item B<-chain> certs_file.pem
The collection of certificates in PEM format that will all
@@ -224,7 +264,7 @@ contain the certificate chain for the signer certificate from its
issuer upwards. The B<-reply> command does not build a certificate
chain automatically. (Optional)
=item B<-policy> object_id
=item B<-tspolicy> object_id
The default policy to use for the response unless the client
explicitly requires a particular TSA policy. The OID can be specified
@@ -283,7 +323,7 @@ data file. The B<-verify> command does not use the configuration file.
=item B<-data> file_to_hash
The response or token must be verified against file_to_hash. The file
is hashed with the message digest algorithm specified in the token.
is hashed with the message digest algorithm specified in the token.
The B<-digest> and B<-queryfile> options must not be specified with this one.
(Optional)
@@ -311,16 +351,16 @@ of a time stamp response (TimeStampResp). (Optional)
=item B<-CApath> trusted_cert_path
The name of the directory containing the trused CA certificates of the
client. See the similar option of L<verify(1)|verify(1)> for additional
The name of the directory containing the trusted CA certificates of the
client. See the similar option of L<verify(1)> for additional
details. Either this option or B<-CAfile> must be specified. (Optional)
=item B<-CAfile> trusted_certs.pem
The name of the file containing a set of trusted self-signed CA
certificates in PEM format. See the similar option of
L<verify(1)|verify(1)> for additional details. Either this option
The name of the file containing a set of trusted self-signed CA
certificates in PEM format. See the similar option of
L<verify(1)> for additional details. Either this option
or B<-CApath> must be specified.
(Optional)
@@ -332,12 +372,24 @@ certificate. This file must contain the TSA signing certificate and
all intermediate CA certificates unless the response includes them.
(Optional)
=item I<verify options>
The options B<-attime timestamp>, B<-check_ss_sig>, B<-crl_check>,
B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>,
B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>,
B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>,
B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>,
B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>,
B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>,
B<-verify_name>, and B<-x509_strict> can be used to control timestamp
verification. See L<verify(1)>.
=back
=head1 CONFIGURATION FILE OPTIONS
The B<-query> and B<-reply> commands make use of a configuration file
defined by the B<OPENSSL_CONF> environment variable. See L<config(5)|config(5)>
defined by the B<OPENSSL_CONF> environment variable. See L<config(5)>
for a general description of the syntax of the config file. The
B<-query> command uses only the symbolic OID names section
and it can work without it. However, the B<-reply> command needs the
@@ -348,7 +400,7 @@ switch always overrides the settings in the config file.
=over 4
=item B<tsa> section, B<default_tsa>
=item B<tsa> section, B<default_tsa>
This is the main section and it specifies the name of another section
that contains all the options for the B<-reply> command. This default
@@ -356,15 +408,15 @@ section can be overridden with the B<-section> command line switch. (Optional)
=item B<oid_file>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<oid_section>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<RANDFILE>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<serial>
@@ -375,9 +427,9 @@ generation a new file is created with serial number 1. (Mandatory)
=item B<crypto_device>
Specifies the OpenSSL engine that will be set as the default for
all available algorithms. The default value is builtin, you can specify
any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM).
Specifies the GmSSL engine that will be set as the default for
all available algorithms. The default value is builtin, you can specify
any other engines supported by GmSSL (e.g. use chil for the NCipher HSM).
(Optional)
=item B<signer_cert>
@@ -396,10 +448,15 @@ option. (Optional)
The private key of the TSA in PEM format. The same as the B<-inkey>
command line option. (Optional)
=item B<signer_digest>
Signing digest to use. The same as the
B<-sha1|-sha224|-sha256|-sha384|-sha512> command line option. (Optional)
=item B<default_policy>
The default policy to use when the request does not mandate any
policy. The same as the B<-policy> command line option. (Optional)
policy. The same as the B<-tspolicy> command line option. (Optional)
=item B<other_policies>
@@ -419,7 +476,7 @@ the components is missing zero is assumed for that field. (Optional)
=item B<clock_precision_digits>
Specifies the maximum number of digits, which represent the fraction of
Specifies the maximum number of digits, which represent the fraction of
seconds, that need to be included in the time field. The trailing zeroes
must be removed from the time, so there might actually be fewer digits,
or no fraction of seconds at all. Supported only on UNIX platforms.
@@ -458,34 +515,34 @@ overridden by the B<-config> command line option.
=head1 EXAMPLES
All the examples below presume that B<OPENSSL_CONF> is set to a proper
configuration file, e.g. the example configuration file
openssl/apps/openssl.cnf will do.
configuration file, e.g. the example configuration file
gmssl/apps/openssl.cnf will do.
=head2 Time Stamp Request
To create a time stamp request for design1.txt with SHA-1
To create a time stamp request for design1.txt with SHA-1
without nonce and policy and no certificate is required in the response:
openssl ts -query -data design1.txt -no_nonce \
-out design1.tsq
gmssl ts -query -data design1.txt -no_nonce \
-out design1.tsq
To create a similar time stamp request with specifying the message imprint
explicitly:
openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-no_nonce -out design1.tsq
gmssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-no_nonce -out design1.tsq
To print the content of the previous request in human readable format:
openssl ts -query -in design1.tsq -text
gmssl ts -query -in design1.tsq -text
To create a time stamp request which includes the MD-5 digest
To create a time stamp request which includes the MD-5 digest
of design2.txt, requests the signer certificate and nonce,
specifies a policy id (assuming the tsa_policy1 name is defined in the
OID section of the config file):
openssl ts -query -data design2.txt -md5 \
-policy tsa_policy1 -cert -out design2.tsq
gmssl ts -query -data design2.txt -md5 \
-tspolicy tsa_policy1 -cert -out design2.tsq
=head2 Time Stamp Response
@@ -493,61 +550,61 @@ Before generating a response a signing certificate must be created for
the TSA that contains the B<timeStamping> critical extended key usage extension
without any other key usage extensions. You can add the
'extendedKeyUsage = critical,timeStamping' line to the user certificate section
of the config file to generate a proper certificate. See L<req(1)|req(1)>,
L<ca(1)|ca(1)>, L<x509(1)|x509(1)> for instructions. The examples
of the config file to generate a proper certificate. See L<req(1)>,
L<ca(1)>, L<x509(1)> for instructions. The examples
below assume that cacert.pem contains the certificate of the CA,
tsacert.pem is the signing certificate issued by cacert.pem and
tsakey.pem is the private key of the TSA.
To create a time stamp response for a request:
openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
-signer tsacert.pem -out design1.tsr
gmssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
-signer tsacert.pem -out design1.tsr
If you want to use the settings in the config file you could just write:
openssl ts -reply -queryfile design1.tsq -out design1.tsr
gmssl ts -reply -queryfile design1.tsq -out design1.tsr
To print a time stamp reply to stdout in human readable format:
openssl ts -reply -in design1.tsr -text
gmssl ts -reply -in design1.tsr -text
To create a time stamp token instead of time stamp response:
openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
gmssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
To print a time stamp token to stdout in human readable format:
openssl ts -reply -in design1_token.der -token_in -text -token_out
gmssl ts -reply -in design1_token.der -token_in -text -token_out
To extract the time stamp token from a response:
openssl ts -reply -in design1.tsr -out design1_token.der -token_out
gmssl ts -reply -in design1.tsr -out design1_token.der -token_out
To add 'granted' status info to a time stamp token thereby creating a
valid response:
openssl ts -reply -in design1_token.der -token_in -out design1.tsr
gmssl ts -reply -in design1_token.der -token_in -out design1.tsr
=head2 Time Stamp Verification
To verify a time stamp reply against a request:
openssl ts -verify -queryfile design1.tsq -in design1.tsr \
-CAfile cacert.pem -untrusted tsacert.pem
gmssl ts -verify -queryfile design1.tsq -in design1.tsr \
-CAfile cacert.pem -untrusted tsacert.pem
To verify a time stamp reply that includes the certificate chain:
openssl ts -verify -queryfile design2.tsq -in design2.tsr \
-CAfile cacert.pem
gmssl ts -verify -queryfile design2.tsq -in design2.tsr \
-CAfile cacert.pem
To verify a time stamp token against the original data file:
openssl ts -verify -data design2.txt -in design2.tsr \
-CAfile cacert.pem
gmssl ts -verify -data design2.txt -in design2.tsr \
-CAfile cacert.pem
To verify a time stamp token against a message imprint:
openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-in design2.tsr -CAfile cacert.pem
gmssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-in design2.tsr -CAfile cacert.pem
You could also look at the 'test' directory for more examples.
@@ -559,14 +616,14 @@ Zoltan Glozik <zglozik@opentsa.org>. Known issues:
=over 4
=item * No support for time stamps over SMTP, though it is quite easy
to implement an automatic e-mail based TSA with L<procmail(1)|procmail(1)>
and L<perl(1)|perl(1)>. HTTP server support is provided in the form of
to implement an automatic e-mail based TSA with L<procmail(1)>
and L<perl(1)>. HTTP server support is provided in the form of
a separate apache module. HTTP client support is provided by
L<tsget(1)|tsget(1)>. Pure TCP/IP protocol is not supported.
L<tsget(1)>. Pure TCP/IP protocol is not supported.
=item * The file containing the last serial number of the TSA is not
locked when being read or written. This is a problem if more than one
instance of L<openssl(1)|openssl(1)> is trying to create a time stamp
instance of L<gmssl(1)> is trying to create a time stamp
response at the same time. This is not an issue when using the apache
server module, it does proper locking.
@@ -579,16 +636,19 @@ test/testtsa).
=back
=cut
=head1 AUTHOR
Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
=head1 SEE ALSO
L<tsget(1)|tsget(1)>, L<openssl(1)|openssl(1)>, L<req(1)|req(1)>,
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<config(5)|config(5)>
L<tsget(1)>, L<gmssl(1)>, L<req(1)>,
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
L<config(5)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

53
doc/apps/tsget.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
tsget - Time Stamping HTTP/HTTPS client
@@ -26,22 +28,22 @@ B<-h> server_url
The B<tsget> command can be used for sending a time stamp request, as
specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing
the time stamp response in a file. This tool cannot be used for creating the
requests and verifying responses, you can use the OpenSSL B<ts(1)> command to
requests and verifying responses, you can use the GmSSL B<ts(1)> command to
do that. B<tsget> can send several requests to the server without closing
the TCP connection if more than one requests are specified on the command
line.
The tool sends the following HTTP request for each time stamp request:
POST url HTTP/1.1
User-Agent: OpenTSA tsget.pl/<version>
Host: <host>:<port>
Pragma: no-cache
Content-Type: application/timestamp-query
Accept: application/timestamp-reply
Content-Length: length of body
POST url HTTP/1.1
User-Agent: OpenTSA tsget.pl/<version>
Host: <host>:<port>
Pragma: no-cache
Content-Type: application/timestamp-query
Accept: application/timestamp-reply
Content-Length: length of body
...binary request specified by the user...
...binary request specified by the user...
B<tsget> expects a response of type application/timestamp-reply, which is
written to a file without any interpretation.
@@ -108,7 +110,7 @@ Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional)
(HTTPS) The path containing the trusted CA certificates to verify the peer's
certificate. The directory must be prepared with the B<c_rehash>
OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of
GmSSL utility. Either option B<-C> or option B<-P> must be given in case of
HTTPS. (Optional)
=item B<-rand> file:file...
@@ -142,7 +144,7 @@ time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
and at port 8443 for HTTPS requests, the TSA service is available at the /tsa
absolute path.
Get a time stamp response for file1.tsq over HTTP, output is written to
Get a time stamp response for file1.tsq over HTTP, output is written to
file1.tsr:
tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq
@@ -151,44 +153,49 @@ Get a time stamp response for file1.tsq and file2.tsq over HTTP showing
progress, output is written to file1.reply and file2.reply respectively:
tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \
file1.tsq file2.tsq
file1.tsq file2.tsq
Create a time stamp request, write it to file3.tsq, send it to the server and
write the response to file3.tsr:
openssl ts -query -data file3.txt -cert | tee file3.tsq \
| tsget -h http://tsa.opentsa.org:8080/tsa \
-o file3.tsr
gmssl ts -query -data file3.txt -cert | tee file3.tsq \
| tsget -h http://tsa.opentsa.org:8080/tsa \
-o file3.tsr
Get a time stamp response for file1.tsq over HTTPS without client
authentication:
tsget -h https://tsa.opentsa.org:8443/tsa \
-C cacerts.pem file1.tsq
-C cacerts.pem file1.tsq
Get a time stamp response for file1.tsq over HTTPS with certificate-based
client authentication (it will ask for the passphrase if client_key.pem is
protected):
tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
-k client_key.pem -c client_cert.pem file1.tsq
-k client_key.pem -c client_cert.pem file1.tsq
You can shorten the previous command line if you make use of the B<TSGET>
environment variable. The following commands do the same as the previous
example:
TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
-k client_key.pem -c client_cert.pem'
-k client_key.pem -c client_cert.pem'
export TSGET
tsget file1.tsq
=head1 AUTHOR
Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
=head1 SEE ALSO
L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>,
L<gmssl(1)>, L<ts(1)>, L<curl(1)>,
B<RFC 3161>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

739
doc/apps/verify.pod
View File

@@ -1,50 +1,81 @@
=pod
=encoding utf8
=head1 NAME
verify - Utility to verify certificates.
verify - Utility to verify certificates
=head1 SYNOPSIS
B<openssl> B<verify>
[B<-CApath directory>]
B<gmssl> B<verify>
[B<-help>]
[B<-CAfile file>]
[B<-purpose purpose>]
[B<-policy arg>]
[B<-ignore_critical>]
[B<-CApath directory>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-allow_proxy_certs>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crlfile file>]
[B<-CRLfile file>]
[B<-crl_download>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-policy_check>]
[B<-engine id>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-x509_strict>]
[B<-extended_crl>]
[B<-use_deltas>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-allow_proxy_certs>]
[B<-untrusted file>]
[B<-help>]
[B<-issuer_checks>]
[B<-trusted file>]
[B<-use_deltas>]
[B<-verbose>]
[B<-auth_level level>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-show_chain>]
[B<->]
[certificates]
=head1 DESCRIPTION
The B<verify> command verifies certificate chains.
=head1 COMMAND OPTIONS
verify命令验证证书链。
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
打印使用信息。
=item B<-CAfile file>
A B<file> of trusted certificates.
The file should contain one or more certificates in PEM format.
可信证书文件。该文件应包含在一个或多个PEM格式的证书里。
=item B<-CApath directory>
A directory of trusted certificates. The certificates should have names
@@ -53,9 +84,27 @@ form ("hash" is the hashed certificate subject name: see the B<-hash> option
of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
create symbolic links to a directory of certificates.
=item B<-CAfile file>
A file of trusted certificates. The file should contain multiple certificates
in PEM format concatenated together.
可信证书目录。 证书应具有以下格式的名称：hash.0或具有此表单的符号链接
（“哈希”是散列的证书主题名称：请参阅x509实用程序的-hash选项）。 在Unix下，
c_rehash脚本将自动创建到证书目录的符号链接。
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
不要从默认文件位置加载受信任的CA证书。
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
不要从默认目录位置加载受信任的CA证书。
=item B<-allow_proxy_certs>
Allow the verification of proxy certificates
允许验证代理证书。
=item B<-attime timestamp>
@@ -63,28 +112,128 @@ Perform validation checks using time specified by B<timestamp> and not
current system time. B<timestamp> is the number of seconds since
01.01.1970 (UNIX time).
使用由时间戳指定的时间而不是当前系统时间执行验证检查。 时间戳是自01.01.1970（UNIX时间）以来的秒数。
=item B<-check_ss_sig>
Verify the signature on the self-signed root CA. This is disabled by default
because it doesn't add any security.
=item B<-crlfile file>
验证自签名根CA上的签名。 这是默认禁用的，因为它不添加任何安全性。
File containing one or more CRL's (in PEM format) to load.
=item B<-CRLfile file>
The B<file> should contain one or more CRLs in PEM format.
This option can be specified more than once to include CRLs from multiple
B<files>.
文件应包含一个或多个PEM格式的CRL。 可以多次指定此选项以包含来自多个文件的CRL。
=item B<-crl_download>
Attempt to download CRL information for this certificate.
尝试下载此证书的CRL信息。
=item B<-crl_check>
Checks end entity certificate validity by attempting to look up a valid CRL.
If a valid CRL cannot be found an error occurs.
=item B<-untrusted file>
通过尝试查找有效的CRL来检查终端实体证书的有效性。 如果找不到有效的CRL，则会发生错误。
A file of untrusted certificates. The file should contain multiple certificates
in PEM format concatenated together.
=item B<-crl_check_all>
Checks the validity of B<all> certificates in the chain by attempting
to look up valid CRLs.
通过尝试查找有效的CRL来检查链中所有证书的有效性。
=item B<-engine id>
Specifying an engine B<id> will cause L<verify(1)> to attempt to load the
specified engine.
The engine will then be set as the default for all its supported algorithms.
If you want to load certificates or CRLs that require engine support via any of
the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
must be specified before those options.
指定引擎ID将导致verify（1）尝试加载指定的引擎。 引擎将被设置为所有支持的算法的默认值。
如果要通过任何-trusted，-untrusted或-CRLfile选项加载需要引擎支持的证书或CRL，
则必须在这些选项之前指定-engine选项。
=item B<-explicit_policy>
Set policy variable require-explicit-policy (see RFC5280).
设置策略变量require-explicit-policy（参见RFC5280）。
=item B<-extended_crl>
Enable extended CRL features such as indirect CRLs and alternate CRL
signing keys.
启用扩展CRL功能，如间接CRL和备用CRL签名密钥
=item B<-ignore_critical>
Normally if an unhandled critical extension is present which is not
supported by GmSSL the certificate is rejected (as required by RFC5280).
If this option is set critical extensions are ignored.
通常如果GmSSL不支持未处理的关键扩展，那么证书将被拒绝（根据RFC5280的要求）。
如果设置了此选项，则将忽略关键扩展。
=item B<-inhibit_any>
Set policy variable inhibit-any-policy (see RFC5280).
设置策略变量suppress-any-policy（参见RFC5280）。
=item B<-inhibit_map>
Set policy variable inhibit-policy-mapping (see RFC5280).
设置策略变量inhibit-policy-mapping（参见RFC5280）。
=item B<-no_check_time>
This option suppresses checking the validity period of certificates and CRLs
against the current time. If option B<-attime timestamp> is used to specify
a verification time, the check is not suppressed.
此选项禁止根据当前时间检查证书和CRL的有效期。
如果选项-attime时间戳用于指定验证时间，则不会抑制该检查。
=item B<-partial_chain>
Allow verification to succeed even if a I<complete> chain cannot be built to a
self-signed trust-anchor, provided it is possible to construct a chain to a
trusted certificate that might not be self-signed.
即使完整的链不能构建一个自签署的信任锚点也可以允许验证成功，
这可以构建一个链链接到一个不是自签署的受信任证书。
=item B<-policy arg>
Enable policy processing and add B<arg> to the user-initial-policy-set (see
RFC5280). The policy B<arg> can be an object name an OID in numeric form.
This argument can appear more than once.
启用策略处理，并将arg添加到用户初始策略集（请参阅RFC5280）。
策略参数可以是一个数字形式的OID的对象名称。 这个参数可能会出现不止一次。
=item B<-policy_check>
Enables certificate policy processing.
启用证书策略处理。
=item B<-policy_print>
Print out diagnostics related to policy processing.
打印与策略处理有关的诊断。
=item B<-purpose purpose>
@@ -94,99 +243,177 @@ Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more
information.
=item B<-help>
证书的预期用途。 如果未指定此选项，验证将不会在链验证期间考虑证书目的。
目前接受的用途是sslclient，sslserver，nssslserver，smimesign，smimeencrypt。
有关详细信息，请参阅“验证操作”部分。
Print out a usage message.
=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
192 bit, or only 192 bit Level of Security respectively.
See RFC6460 for details. In particular the supported signature algorithms are
reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
P-256 and P-384.
启用Suite B模式操作，分别为128位安全级别，128位或192位或仅192位安全级别。
有关详细信息，请参阅RFC6460。 特别地，支持的签名算法被减少以仅支持ECDSA
和SHA256或SHA384，并且仅支持椭圆曲线P-256和P-384。
=item B<-trusted_first>
When constructing the certificate chain, use the trusted certificates specified
via B<-CAfile>, B<-CApath> or B<-trusted> before any certificates specified via
B<-untrusted>.
This can be useful in environments with Bridge or Cross-Certified CAs.
As of GmSSL 1.1.0 this option is on by default and cannot be disabled.
在构建证书链时，请使用通过-CAfile指定的受信任证书，-CApath或-trusted，然后通过-rustrusted指定任何证书。
这可以在具有桥接或交叉认证CA的环境中使用。 从GmSSL 1.1.0开始，默认情况下，该选项处于打开状态，无法禁用。
=item B<-no_alt_chains>
By default, unless B<-trusted_first> is specified, when building a certificate
chain, if the first certificate chain found is not trusted, then GmSSL will
attempt to replace untrusted issuer certificates with certificates from the
trust store to see if an alternative chain can be found that is trusted.
As of GmSSL 1.1.0, with B<-trusted_first> always on, this option has no
effect.
默认情况下，除非指定了-trusted_first，否则在构建证书链时，如果发现第一个证书链不受信任，
则GmSSL将尝试用信任存储中的证书替换不受信任的颁发者证书，以查看是否可以找到可信任的替代链。
从GmSSL 1.1.0开始，使用-trusted_first始终处于打开状态，此选项不起作用。
=item B<-untrusted file>
A B<file> of additional untrusted certificates (intermediate issuer CAs) used
to construct a certificate chain from the subject certificate to a trust-anchor.
The B<file> should contain one or more certificates in PEM format.
This option can be specified more than once to include untrusted certificates
from multiple B<files>.
用于构建从主题证书到信任锚的证书链的其他不可信证书（中间颁发者CA）的文件。
该文件应包含一个或多个PEM格式的证书。 可以多次指定此选项以包含来自多个文件的不受信任的证书。
=item B<-trusted file>
A B<file> of trusted certificates, which must be self-signed, unless the
B<-partial_chain> option is specified.
The B<file> contains one or more certificates in PEM format.
With this option, no additional (e.g., default) certificate lists are
consulted.
That is, the only trust-anchors are those listed in B<file>.
This option can be specified more than once to include trusted certificates
from multiple B<files>.
This option implies the B<-no-CAfile> and B<-no-CApath> options.
This option cannot be used in combination with either of the B<-CAfile> or
B<-CApath> options.
可信证书的文件，必须是自签名的，除非指定了-partial_chain选项。 该文件包含一个或多个PEM格式的证书。
使用此选项，不会查询附加（例如，默认）证书列表。 也就是说，唯一的信任锚是列出的文件。
可以多次指定此选项以包含来自多个文件的可信证书。 此选项意味着-no-CAfile和-no-CApath选项。
此选项不能与-CAfile或-CApath选项中的任何一个组合使用。
=item B<-use_deltas>
Enable support for delta CRLs.
启用对delta CRL的支持。
=item B<-verbose>
Print extra information about the operations being performed.
=item B<-issuer_checks>
打印有关正在执行的操作的额外信息。
Print out diagnostics relating to searches for the issuer certificate of the
current certificate. This shows why each candidate issuer certificate was
rejected. The presence of rejection messages does not itself imply that
anything is wrong; during the normal verification process, several
rejections may take place.
=item B<-auth_level level>
=item B<-policy arg>
Set the certificate chain authentication security level to B<level>.
The authentication security level determines the acceptable signature and
public key strength when verifying certificate chains.
For a certificate chain to validate, the public keys of all the certificates
must meet the specified security B<level>.
The signature algorithm security level is enforced for all the certificates in
the chain except for the chain's I<trust anchor>, which is either directly
trusted or validated by means other than its signature.
See L<SSL_CTX_set_security_level(3)> for the definitions of the available
levels.
The default security level is -1, or "not set".
At security level 0 or lower all algorithms are acceptable.
Security level 1 requires at least 80-bit-equivalent security and is broadly
interoperable, though it will, for example, reject MD5 signatures or RSA keys
shorter than 1024 bits.
Enable policy processing and add B<arg> to the user-initial-policy-set (see
RFC5280). The policy B<arg> can be an object name an OID in numeric form.
This argument can appear more than once.
将证书链认证安全级别设置为级别。 认证安全级别在验证证书链时确定可接受的签名和公开密钥强度。
要验证证书链，所有证书的公钥必须满足指定的安全级别。 对链中的所有证书执行签名算法安全级别，
除了该链的信任锚，其通过除签名之外的方式直接受信任或验证。 有关可用级别的定义，请参阅SSL_CTX_set_security_level（3）。
默认安全级别为-1或“未设置”。 在0或更低的安全级别，所有算法都可以接受。 安全级别1需要至少80位等效的安全性，
并且可以广泛地互操作，尽管它将例如拒绝MD5签名或短于1024位的RSA密钥。
=item B<-policy_check>
=item B<-verify_depth num>
Enables certificate policy processing.
Limit the certificate chain to B<num> intermediate CA certificates.
A maximal depth chain can have up to B<num+2> certificates, since neither the
end-entity certificate nor the trust-anchor certificate count against the
B<-verify_depth> limit.
=item B<-explicit_policy>
将证书链限制为中间CA证书。 最大深度链可以具有最多num + 2个证书，因为终端实体证书和信任锚证书都不符合-verify_depth限制。
Set policy variable require-explicit-policy (see RFC5280).
=item B<-verify_email email>
=item B<-inhibit_any>
Verify if the B<email> matches the email address in Subject Alternative Name or
the email in the subject Distinguished Name.
Set policy variable inhibit-any-policy (see RFC5280).
验证电子邮件是否匹配主题备用名称中的电子邮件地址或主题可分辨名称中的电子邮件。
=item B<-inhibit_map>
=item B<-verify_hostname hostname>
Set policy variable inhibit-policy-mapping (see RFC5280).
Verify if the B<hostname> matches DNS name in Subject Alternative Name or
Common Name in the subject certificate.
=item B<-no_alt_chains>
验证主题名称是否匹配主题证书中主题备用名称或公用名称中的DNS名称。
When building a certificate chain, if the first certificate chain found is not
trusted, then OpenSSL will continue to check to see if an alternative chain can
be found that is trusted. With this option that behaviour is suppressed so that
only the first chain found is ever used. Using this option will force the
behaviour to match that of previous OpenSSL versions.
=item B<-verify_ip ip>
=item B<-allow_proxy_certs>
Verify if the B<ip> matches the IP address in Subject Alternative Name of
the subject certificate.
Allow the verification of proxy certificates.
验证IP匹配主题证书的主题备用名称中的IP地址。
=item B<-trusted file>
=item B<-verify_name name>
A file of additional trusted certificates. The file should contain multiple
certificates in PEM format concatenated together.
Use default verification policies like trust model and required certificate
policies identified by B<name>.
The trust model determines which auxiliary trust or reject OIDs are applicable
to verifying the given certificate chain.
See the B<-addtrust> and B<-addreject> options of the L<x509(1)> command-line
utility.
Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
B<ssl_client>, B<ssl_server>.
These mimics the combinations of purpose and trust settings used in SSL, CMS
and S/MIME.
As of GmSSL 1.1.0, the trust model is inferred from the purpose when not
specified, so the B<-verify_name> options are functionally equivalent to the
corresponding B<-purpose> settings.
=item B<-policy_print>
Print out diagnostics related to policy processing.
=item B<-crl_check>
Checks end entity certificate validity by attempting to look up 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 look up 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 RFC5280).
If this option is set critical extensions are ignored.
使用默认验证策略，如信任模型和由名称标识的所需证书策略。 信任模型确定哪些辅助信任或拒绝OID适用于验证给定的证书链。
请参阅x509（1）命令行实用程序的-addtrust和-addreject选项。 支持的策略名称包括：default，pkcs7，smime_sign，ssl_client，ssl_server。
这些模拟了SSL，CMS和S / MIME中使用的目的和信任设置的组合。 从GmSSL 1.1.0开始，从未指定的目的推断信任模型
，因此-verify_name选项在功能上等同于相应的设置。
=item B<-x509_strict>
For strict X.509 compliance, disable non-compliant workarounds for broken
certificates.
=item B<-extended_crl>
对于严格的X.509合规性，请禁用破坏的证书的不符合标准的解决方法。
Enable extended CRL features such as indirect CRLs and alternate CRL
signing keys.
=item B<-show_chain>
=item B<-use_deltas>
Display information about the certificate chain that has been built (if
successful). Certificates in the chain that came from the untrusted list will be
flagged as "untrusted".
Enable support for delta CRLs.
=item B<-check_ss_sig>
Verify the signature on the self-signed root CA. This is disabled by default
because it doesn't add any security.
显示有关已建立的证书链的信息（如果成功）。 来自不受信任名单的链中的证书将被标记为“不受信任”。
=item B<->
@@ -194,12 +421,16 @@ Indicates the last option. All arguments following this are assumed to be
certificate files. This is useful if the first certificate filename begins
with a B<->.
表示最后一个选项。 以下所有参数都被认为是证书文件。 如果第一个证书文件名以 - 开头，这将非常有用。
=item B<certificates>
One or more certificates to verify. If no certificates are given, B<verify>
will attempt to read a certificate from standard input. Certificates must be
in PEM format.
一个或多个验证证书。 如果没有给出证书，验证将尝试从标准输入读取证书。 证书必须采用PEM格式。
=back
=head1 VERIFY OPERATION
@@ -217,21 +448,21 @@ determined.
The verify operation consists of a number of separate steps.
Firstly a certificate chain is built up starting from the supplied certificate
and ending in the root CA. It is an error if the whole chain cannot be built
up. The chain is built up by looking up the issuers certificate of the current
certificate. If a certificate is found which is its own issuer it is assumed
to be the root CA.
and ending in the root CA.
It is an error if the whole chain cannot be built up.
The chain is built up by looking up the issuers certificate of the current
certificate.
If a certificate is found which is its own issuer it is assumed to be the root
CA.
The process of 'looking up the issuers certificate' itself involves a number
of steps. In versions of OpenSSL before 0.9.5a the first certificate whose
subject name matched the issuer of the current certificate was assumed to be
the issuers certificate. In OpenSSL 0.9.6 and later all certificates
whose subject name matches the issuer name of the current certificate are
subject to further tests. The relevant authority key identifier components
of the current certificate (if present) must match the subject key identifier
(if present) and issuer and serial number of the candidate issuer, in addition
the keyUsage extension of the candidate issuer (if present) must permit
certificate signing.
The process of 'looking up the issuers certificate' itself involves a number of
steps.
After all certificates whose subject name matches the issuer name of the current
certificate are subject to further tests.
The relevant authority key identifier components of the current certificate (if
present) must match the subject key identifier (if present) and issuer and
serial number of the candidate issuer, in addition the keyUsage extension of
the candidate issuer (if present) must permit certificate signing.
The lookup first looks in the list of untrusted certificates and if no match
is found the remaining lookups are from the trusted certificates. The root CA
@@ -246,10 +477,10 @@ compatible with the supplied purpose and all other certificates must also be val
CA certificates. The precise extensions required are described in more detail in
the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
The third operation is to check the trust settings on the root CA. The root
CA should be trusted for the supplied purpose. For compatibility with previous
versions of SSLeay and OpenSSL a certificate with no trust settings is considered
to be valid for all purposes.
The third operation is to check the trust settings on the root CA. The root CA
should be trusted for the supplied purpose.
For compatibility with previous versions of GmSSL, a certificate with no
trust settings is considered to be valid for all purposes.
The final operation is to check the validity of the certificate chain. The validity
period is checked against the current system time and the notBefore and notAfter
@@ -274,160 +505,296 @@ problem was detected starting with zero for the certificate being verified itsel
then 1 for the CA that signed the certificate and so on. Finally a text version
of the error number is presented.
An exhaustive list of the error codes and messages is shown below, this also
A partial list of the error codes and messages is shown below, this also
includes the name of the error code as defined in the header file x509_vfy.h
Some of the error codes are defined but never returned: these are described
as "unused".
=over 4
=item B<0 X509_V_OK: ok>
=item B<X509_V_OK>
the operation was successful.
The operation was successful.
=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
=item B<X509_V_ERR_UNSPECIFIED>
the issuer certificate of a looked up certificate could not be found. This
Unspecified error; should not happen.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT>
The issuer certificate of a looked up certificate could not be found. This
normally means the list of trusted certificates is not complete.
=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
=item B<X509_V_ERR_UNABLE_TO_GET_CRL>
the CRL of a certificate could not be found.
The CRL of a certificate could not be found.
=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
the certificate signature could not be decrypted. This means that the actual signature value
The certificate signature could not be decrypted. This means that the actual signature value
could not be determined rather than it not matching the expected value, this is only
meaningful for RSA keys.
=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
the CRL signature could not be decrypted: this means that the actual signature value
The CRL signature could not be decrypted: this means that the actual signature value
could not be determined rather than it not matching the expected value. Unused.
=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
the public key in the certificate SubjectPublicKeyInfo could not be read.
The public key in the certificate SubjectPublicKeyInfo could not be read.
=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
the signature of the certificate is invalid.
The signature of the certificate is invalid.
=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
the signature of the certificate is invalid.
The signature of the certificate is invalid.
=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
=item B<X509_V_ERR_CERT_NOT_YET_VALID>
the certificate is not yet valid: the notBefore date is after the current time.
The certificate is not yet valid: the notBefore date is after the current time.
=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
=item B<X509_V_ERR_CERT_HAS_EXPIRED>
the certificate has expired: that is the notAfter date is before the current time.
The certificate has expired: that is the notAfter date is before the current time.
=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
=item B<X509_V_ERR_CRL_NOT_YET_VALID>
the CRL is not yet valid.
The CRL is not yet valid.
=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
=item B<X509_V_ERR_CRL_HAS_EXPIRED>
the CRL has expired.
The CRL has expired.
=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
the certificate notBefore field contains an invalid time.
The certificate notBefore field contains an invalid time.
=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
the certificate notAfter field contains an invalid time.
The certificate notAfter field contains an invalid time.
=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
the CRL lastUpdate field contains an invalid time.
The CRL lastUpdate field contains an invalid time.
=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
the CRL nextUpdate field contains an invalid time.
The CRL nextUpdate field contains an invalid time.
=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
=item B<X509_V_ERR_OUT_OF_MEM>
an error occurred trying to allocate memory. This should never happen.
An error occurred trying to allocate memory. This should never happen.
=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT>
the passed certificate is self signed and the same certificate cannot be found in the list of
The passed certificate is self-signed and the same certificate cannot be found in the list of
trusted certificates.
=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN>
the certificate chain could be built up using the untrusted certificates but the root could not
The certificate chain could be built up using the untrusted certificates but the root could not
be found locally.
=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
the issuer certificate could not be found: this occurs if the issuer
The issuer certificate could not be found: this occurs if the issuer
certificate of an untrusted certificate cannot be found.
=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE>
no signatures could be verified because the chain contains only one certificate and it is not
No signatures could be verified because the chain contains only one certificate and it is not
self signed.
=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
the certificate chain length is greater than the supplied maximum depth. Unused.
The certificate chain length is greater than the supplied maximum depth. Unused.
=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
=item B<X509_V_ERR_CERT_REVOKED>
the certificate has been revoked.
The certificate has been revoked.
=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
=item B<X509_V_ERR_INVALID_CA>
a CA certificate is invalid. Either it is not a CA or its extensions are not consistent
A CA certificate is invalid. Either it is not a CA or its extensions are not consistent
with the supplied purpose.
=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
the basicConstraints pathlength parameter has been exceeded.
The basicConstraints pathlength parameter has been exceeded.
=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
=item B<X509_V_ERR_INVALID_PURPOSE>
the supplied certificate cannot be used for the specified purpose.
The supplied certificate cannot be used for the specified purpose.
=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
=item B<X509_V_ERR_CERT_UNTRUSTED>
the root CA is not marked as trusted for the specified purpose.
=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected>
=item B<X509_V_ERR_CERT_REJECTED>
the root CA is marked to reject the specified purpose.
The root CA is marked to reject the specified purpose.
=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH>
the current candidate issuer certificate was rejected because its subject name
did not match the issuer name of the current certificate. Only displayed when
the B<-issuer_checks> option is set.
not used as of GmSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
=item B<X509_V_ERR_AKID_SKID_MISMATCH>
the current candidate issuer certificate was rejected because its subject key
identifier was present and did not match the authority key identifier current
certificate. Only displayed when the B<-issuer_checks> option is set.
Not used as of GmSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH>
the current candidate issuer certificate was rejected because its issuer name
and serial number was present and did not match the authority key identifier
of the current certificate. Only displayed when the B<-issuer_checks> option is set.
Not used as of GmSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
the current candidate issuer certificate was rejected because its keyUsage extension
does not permit certificate signing.
Not used as of GmSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
an application specific error. Unused.
Unable to get CRL issuer certificate.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION>
Unhandled critical extension.
=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN>
Key usage does not include CRL signing.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION>
Unhandled critical CRL extension.
=item B<X509_V_ERR_INVALID_NON_CA>
Invalid non-CA certificate has CA markings.
=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED>
Proxy path length constraint exceeded.
=item B<X509_V_ERR_PROXY_SUBJECT_INVALID>
Proxy certificate subject is invalid. It MUST be the same as the issuer
with a single CN component added.
=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE>
Key usage does not include digital signature.
=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED>
Proxy certificates not allowed, please use B<-allow_proxy_certs>.
=item B<X509_V_ERR_INVALID_EXTENSION>
Invalid or inconsistent certificate extension.
=item B<X509_V_ERR_INVALID_POLICY_EXTENSION>
Invalid or inconsistent certificate policy extension.
=item B<X509_V_ERR_NO_EXPLICIT_POLICY>
No explicit policy.
=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE>
Different CRL scope.
=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE>
Unsupported extension feature.
=item B<X509_V_ERR_UNNESTED_RESOURCE>
RFC 3779 resource not subset of parent's resources.
=item B<X509_V_ERR_PERMITTED_VIOLATION>
Permitted subtree violation.
=item B<X509_V_ERR_EXCLUDED_VIOLATION>
Excluded subtree violation.
=item B<X509_V_ERR_SUBTREE_MINMAX>
Name constraints minimum and maximum not supported.
=item B<X509_V_ERR_APPLICATION_VERIFICATION>
Application verification failure. Unused.
=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>
Unsupported name constraint type.
=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX>
Unsupported or invalid name constraint syntax.
=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>
Unsupported or invalid name syntax.
=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR>
CRL path validation error.
=item B<X509_V_ERR_PATH_LOOP>
Path loop.
=item B<X509_V_ERR_SUITE_B_INVALID_VERSION>
Suite B: certificate version invalid.
=item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM>
Suite B: invalid public key algorithm.
=item B<X509_V_ERR_SUITE_B_INVALID_CURVE>
Suite B: invalid ECC curve.
=item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM>
Suite B: invalid signature algorithm.
=item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED>
Suite B: curve not allowed for this LOS.
=item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256>
Suite B: cannot sign P-384 with P-256.
=item B<X509_V_ERR_HOSTNAME_MISMATCH>
Hostname mismatch.
=item B<X509_V_ERR_EMAIL_MISMATCH>
Email address mismatch.
=item B<X509_V_ERR_IP_ADDRESS_MISMATCH>
IP address mismatch.
=item B<X509_V_ERR_DANE_NO_MATCH>
DANE TLSA authentication is enabled, but no TLSA records matched the
certificate chain.
This error is only possible in L<s_client(1)>.
=back
@@ -436,22 +803,34 @@ an application specific error. Unused.
Although the issuer checks are a considerable improvement over the old technique they still
suffer from limitations in the underlying X509_LOOKUP API. One consequence of this is that
trusted certificates with matching subject name must either appear in a file (as specified by the
B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only
B<-CAfile> option) or a directory (as specified by B<-CApath>). If they occur in both then only
the certificates in the file will be recognised.
Previous versions of OpenSSL assume certificates with matching subject name are identical and
Previous versions of GmSSL assume certificates with matching subject name are identical and
mishandled them.
Previous versions of this documentation swapped the meaning of the
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
=head1 SEE ALSO
L<x509(1)|x509(1)>
L<x509(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The B<-show_chain> option was first added to GmSSL 1.1.0.
The B<-issuer_checks> option is deprecated as of GmSSL 1.1.0 and
is silently ignored.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/apps/version.pod
View File

@@ -1,12 +1,15 @@
=pod
=encoding utf8
=head1 NAME
version - print OpenSSL version information
version - print GmSSL version information
=head1 SYNOPSIS
B<openssl version>
B<gmssl version>
[B<-help>]
[B<-a>]
[B<-v>]
[B<-b>]
@@ -14,26 +17,31 @@ B<openssl version>
[B<-f>]
[B<-p>]
[B<-d>]
[B<-e>]
=head1 DESCRIPTION
This command is used to print out version information about OpenSSL.
This command is used to print out version information about GmSSL.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-a>
all information, this is the same as setting all the other flags.
=item B<-v>
the current OpenSSL version.
the current GmSSL version.
=item B<-b>
the date the current version of OpenSSL was built.
the date the current version of GmSSL was built.
=item B<-o>
@@ -51,15 +59,24 @@ platform setting.
OPENSSLDIR setting.
=item B<-e>
ENGINESDIR setting.
=back
=head1 NOTES
The output of B<openssl version -a> would typically be used when sending
The output of B<gmssl version -a> would typically be used when sending
in a bug report.
=head1 HISTORY
=head1 COPYRIGHT
The B<-d> option was added in OpenSSL 0.9.7.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

353
doc/apps/x509.pod
View File

@@ -1,13 +1,15 @@
=pod
=encoding utf8
=head1 NAME
x509 - Certificate display and signing utility
=head1 SYNOPSIS
B<openssl> B<x509>
B<gmssl> B<x509>
[B<-help>]
[B<-inform DER|PEM|NET>]
[B<-outform DER|PEM|NET>]
[B<-keyform DER|PEM>]
@@ -55,7 +57,7 @@ B<openssl> B<x509>
[B<-text>]
[B<-certopt option>]
[B<-C>]
[B<-md2|-md5|-sha1|-mdc2>]
[B<-[digest]>]
[B<-clrext>]
[B<-extfile filename>]
[B<-extensions section>]
@@ -71,12 +73,22 @@ certificate trust settings.
Since there are a large number of options they will split up into
various sections.
x509命令是一个多用途证书实用程序。 它可用于显示证书信息，将证书转换为各种表单，签署诸如“迷你CA”或编辑证书信任设置的证书请求。
由于有大量的选择，它们将分成不同的部分。
=head1 OPTIONS
=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
=head2 Input, Output, and General Purpose Options
=over 4
=item B<-help>
Print out a usage message.
打印使用信息。
=item B<-inform DER|PEM|NET>
This specifies the input format normally the command will expect an X509
@@ -86,27 +98,39 @@ is the base64 encoding of the DER encoding with header and footer lines
added. The NET option is an obscure Netscape server format that is now
obsolete.
这通常指定命令将期望X509证书的输入格式，但如果存在其他选项（如-req），则可以更改该输入格式。 DER格式是证书的DER编码，PEM是添加了页眉和页脚行的DER编码的base64编码。 NET选项是一个晦涩的Netscape服务器格式，现在已经过时了。
=item B<-outform DER|PEM|NET>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
这指定输出格式，这些选项与-inform选项具有相同的含义。
=item B<-in filename>
This specifies the input filename to read a certificate from or standard input
if this option is not specified.
如果未指定此选项，则指定从或从标准输入读取证书的输入文件名。
=item B<-out filename>
This specifies the output filename to write to or standard output by
default.
=item B<-md2|-md5|-sha1|-mdc2>
默认情况下，它指定要写入的输出文件名或标准输出。
the digest to use. This affects any signing or display option that uses a message
digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not
specified then SHA1 is used. If the key being used to sign with is a DSA key
then this option has no effect: SHA1 is always used with DSA keys.
=item B<-[digest]>
the digest to use.
This affects any signing or display option that uses a message
digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options.
Any digest supported by the GmSSL B<dgst> command can be used.
If not specified then SHA1 is used with B<-fingerprint> or
the default digest for the signing algorithm is used, typically SHA256.
消化使用。 这会影响使用消息摘要的任何签名或显示选项，例如-fingerprint，-signkey和-CA选项。 可以使用GmSSL dgst命令支持的任何摘要。 如果没有指定，则SHA1与-fingerprint一起使用，或者使用签名算法的默认摘要，通常为SHA256。
=item B<-engine id>
@@ -115,13 +139,17 @@ 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.
指定引擎（通过其唯一的id字符串）将导致x509尝试获取对指定引擎的功能引用，从而在需要时进行初始化。 然后，引擎将被设置为所有可用算法的默认值。
=back
=head2 DISPLAY OPTIONS
=head2 Display Options
Note: the B<-alias> and B<-purpose> options are also display options
but are described in the B<TRUST SETTINGS> section.
注意：-alias和-purpose选项也是显示选项，但在“信任设置”部分中有介绍。
=over 4
=item B<-text>
@@ -130,6 +158,8 @@ prints out the certificate in text form. Full details are output including the
public key, signature algorithms, issuer and subject names, serial number
any extensions present and any trust settings.
以文本形式打印证书。 输出全部细节，包括公钥，签名算法，发行人和主题名称，任何扩展名的序列号和任何信任设置。
=item B<-certopt option>
customise the output format used with B<-text>. The B<option> argument can be
@@ -137,59 +167,85 @@ a single option or multiple options separated by commas. The B<-certopt> switch
may be also be used more than once to set multiple options. See the B<TEXT OPTIONS>
section for more information.
定制与-text一起使用的输出格式。 选项参数可以是单个选项或多个选项，以逗号分隔。 可以使用-certopt开关多次设置多个选项。 有关详细信息，请参阅TEXT OPTIONS部分。
=item B<-noout>
this option prevents output of the encoded version of the request.
此选项可防止请求的编码版本的输出。
=item B<-pubkey>
outputs the the certificate's SubjectPublicKeyInfo block in PEM format.
outputs the certificate's SubjectPublicKeyInfo block in PEM format.
以PEM格式输出证书的SubjectPublicKeyInfo块。
=item B<-modulus>
this option prints out the value of the modulus of the public key
contained in the certificate.
此选项打印证书中包含的公钥的模数值。
=item B<-serial>
outputs the certificate serial number.
输出证书序列号。
=item B<-subject_hash>
outputs the "hash" of the certificate subject name. This is used in OpenSSL to
outputs the "hash" of the certificate subject name. This is used in GmSSL to
form an index to allow certificates in a directory to be looked up by subject
name.
输出证书主题名称的“哈希”。 这在GmSSL中用于形成索引，以允许以主题名称查找目录中的证书。
=item B<-issuer_hash>
outputs the "hash" of the certificate issuer name.
输出证书颁发者名称的“哈希”。
=item B<-ocspid>
outputs the OCSP hash values for the subject name and public key.
输出主题名称和公钥的OCSP哈希值。
=item B<-hash>
synonym for "-subject_hash" for backward compatibility reasons.
“-subject_hash”的同义词由于向后兼容性原因。
=item B<-subject_hash_old>
outputs the "hash" of the certificate subject name using the older algorithm
as used by OpenSSL versions before 1.0.0.
as used by GmSSL versions before 1.0.0.
使用1.0.0之前的GmSSL版本使用的旧算法输出证书主题名称的“哈希”。
=item B<-issuer_hash_old>
outputs the "hash" of the certificate issuer name using the older algorithm
as used by OpenSSL versions before 1.0.0.
as used by GmSSL versions before 1.0.0.
使用1.0.0之前的GmSSL版本使用的旧算法输出证书颁发者名称的“哈希”。
=item B<-subject>
outputs the subject name.
输出主题名称。
=item B<-issuer>
outputs the issuer name.
输出颁发者名称。
=item B<-nameopt option>
option which determines how the subject or issuer names are displayed. The
@@ -197,45 +253,61 @@ 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 B<NAME OPTIONS> section for more information.
该选项用于确定主题或发行者名称的显示方式。 选项参数可以是单个选项或多个选项，以逗号分隔。 或者，-nameopt开关可以被多次使用以设置多个选项。 有关详细信息，请参阅“NAME OPTIONS”部分。
=item B<-email>
outputs the email address(es) if any.
输出电子邮件地址（如果有）。
=item B<-ocsp_uri>
outputs the OCSP responder address(es) if any.
输出OCSP响应者地址（如果有）。
=item B<-startdate>
prints out the start date of the certificate, that is the notBefore date.
打印证书的开始日期，即notBefore日期。
=item B<-enddate>
prints out the expiry date of the certificate, that is the notAfter date.
打印证书的到期日期，即notAfter日期。
=item B<-dates>
prints out the start and expiry dates of a certificate.
打印证书的开始和到期日期。
=item B<-checkend arg>
checks if the certificate expires within the next B<arg> seconds and exits
non-zero if yes it will expire or zero if not.
检查证书是否在下一个arg秒内到期，如果是，则退出非零，否则为零。
=item B<-fingerprint>
prints out the digest of the DER encoded version of the whole certificate
(see digest options).
打印整个证书的DER编码版本的摘要（请参阅摘要选项）。
=item B<-C>
this outputs the certificate in the form of a C source file.
这将以C源文件的形式输出证书。
=back
=head2 TRUST SETTINGS
Please note these options are currently experimental and may well change.
=head2 Trust Settings
A B<trusted certificate> is an ordinary certificate which has several
additional pieces of information attached to it such as the permitted
@@ -253,9 +325,18 @@ may be trusted for SSL client but not SSL server use.
See the description of the B<verify> utility for more information on the
meaning of trust settings.
Future versions of OpenSSL will recognize trust settings on any
Future versions of GmSSL will recognize trust settings on any
certificate: not just root CAs.
受信任的证书是普通证书，其中附有数个附加的信息，例如证书的许可和禁止使用以及“别名”。
通常当证书被证实时，至少有一个证书必须是“可信任的”。 默认情况下，受信任的证书必须在本地存储，并且必须是根CA：任何以CA为结尾的证书链可用于任何目的。
目前的信任设置仅与根CA一起使用。 它们允许对根CA可以使用的目的进行更精细的控制。 例如，CA可能被信任为SSL客户端，但不能使用SSL服务器。
有关信任设置的含义的更多信息，请参阅验证实用程序的说明。
未来版本的GmSSL将会识别任何证书上的信任设置：不仅仅是根CA。
=over 4
@@ -267,70 +348,100 @@ certificate is output and any trust settings are discarded. With the
B<-trustout> option a trusted certificate is output. A trusted
certificate is automatically output if any trust settings are modified.
这导致x509输出可信证书。 可以输入普通或可信任的证书，但默认情况下会输出普通证书，并丢弃任何信任设置。 使用-trustout选项，输出可信证书。 如果任何信任设置被修改，将自动输出受信任的证书。
=item B<-setalias arg>
sets the alias of the certificate. This will allow the certificate
to be referred to using a nickname for example "Steve's Certificate".
设置证书的别名。 这将允许使用昵称来引用证书，例如“Steve's Certificate”。
=item B<-alias>
outputs the certificate alias, if any.
输出证书别名（如果有）。
=item B<-clrtrust>
clears all the permitted or trusted uses of the certificate.
清除证书的所有允许或受信任的用途。
=item B<-clrreject>
clears all the prohibited or rejected uses of the certificate.
清除证书的所有禁止或拒绝的使用。
=item B<-addtrust arg>
adds a trusted certificate use. Any object name can be used here
but currently only B<clientAuth> (SSL client use), B<serverAuth>
(SSL server use) and B<emailProtection> (S/MIME email) are used.
Other OpenSSL applications may define additional uses.
adds a trusted certificate use.
Any object name can be used here but currently only B<clientAuth> (SSL client
use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and
B<anyExtendedKeyUsage> are used.
As of GmSSL 1.1.0, the last of these blocks all purposes when rejected or
enables all purposes when trusted.
Other GmSSL applications may define additional uses.
添加可信证书使用。 任何对象名称都可以在这里使用，但目前只使用clientAuth（SSL客户端使用），serverAuth（SSL服务器使用），emailProtection（S / MIME电子邮件）和anyExtendedKeyUsage。 从GmSSL 1.1.0开始，最后一个将被拒绝或在受信任时使所有目的成为可能。 其他GmSSL应用程序可能会定义其他用途。
=item B<-addreject arg>
adds a prohibited use. It accepts the same values as the B<-addtrust>
option.
增加禁止使用。 它接受与-addtrust选项相同的值。
=item B<-purpose>
this option performs tests on the certificate extensions and outputs
the results. For a more complete description see the B<CERTIFICATE
EXTENSIONS> section.
此选项对证书扩展进行测试并输出结果。 有关更完整的说明，请参阅CERTIFICATE EXTENSIONS部分。
=back
=head2 SIGNING OPTIONS
=head2 Signing Options
The B<x509> utility can be used to sign certificates and requests: it
can thus behave like a "mini CA".
x509实用程序可用于签署证书和请求：它像“迷你CA”
=over 4
=item B<-signkey filename>
this option causes the input file to be self signed using the supplied
private key.
private key.
If the input file is a certificate it sets the issuer name to the
subject name (i.e. makes it self signed) changes the public key to the
supplied value and changes the start and end dates. The start date is
set to the current time and the end date is set to a value determined
by the B<-days> option. Any certificate extensions are retained unless
the B<-clrext> option is supplied.
the B<-clrext> option is supplied; this includes, for example, any existing
key identifier extensions.
If the input is a certificate request then a self signed certificate
is created using the supplied private key using the subject name in
the request.
此选项将使用提供的私钥对输入文件进行自签名。
如果输入文件是证书，则将发行人名称设置为主题名称（即使其自签名）将公钥更改为提供的值，并更改开始和结束日期。 开始日期设置为当前时间，结束日期设置为由-days选项确定的值。 除非提供了-clrext选项，否则将保留任何证书扩展名; 这包括例如任何现有的密钥标识符扩展。
如果输入是证书请求，则使用提供的私钥使用请求中的主题名称创建自签名证书。
=item B<-passin arg>
the 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<gmssl(1)>.
密码密码来源。 有关arg格式的更多信息，请参阅gmssl（1）中的PASS PHRASE ARGUMENTS部分。
=item B<-clrext>
@@ -339,26 +450,36 @@ certificate is being created from another certificate (for example with
the B<-signkey> or the B<-CA> options). Normally all extensions are
retained.
从证书中删除任何扩展名。 当从另一个证书创建证书时使用此选项（例如使用-signkey或-CA选项）。 通常所有的扩展都保留。
=item B<-keyform PEM|DER>
specifies the format (DER or PEM) of the private key file used in the
B<-signkey> option.
指定-signkey选项中使用的私钥文件的格式（DER或PEM）。
=item B<-days arg>
specifies the number of days to make a certificate valid for. The default
is 30 days.
指定使证书有效的天数。 默认为30天。
=item B<-x509toreq>
converts a certificate into a certificate request. The B<-signkey> option
is used to pass the required private key.
将证书转换为证书请求。 -signkey选项用于传递所需的私钥。
=item B<-req>
by default a certificate is expected on input. With this option a
certificate request is expected instead.
默认情况下，预期输入证书。 使用此选项，可以使用证书请求。
=item B<-set_serial n>
specifies the serial number to use. This option can be used with either
@@ -366,8 +487,11 @@ the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
option the serial number file (as specified by the B<-CAserial> or
B<-CAcreateserial> options) is not used.
The serial number can be decimal or hex (if preceded by B<0x>). Negative
serial numbers can also be specified but their use is not recommended.
The serial number can be decimal or hex (if preceded by B<0x>).
指定要使用的序列号。 此选项可与-signkey或-CA选项一起使用。 如果与-CA选项结合使用，则不使用序列号文件（由-CAserial或-CAcreateserial选项指定）。
序列号可以是十进制或十六进制（如果前面是0x）。
=item B<-CA filename>
@@ -379,12 +503,18 @@ of the CA and it is digitally signed using the CAs private key.
This option is normally combined with the B<-req> option. Without the
B<-req> option the input is a certificate which must be self signed.
指定要用于签名的CA证书。 当此选项存在时，x509的行为就像“迷你CA”。 该CA使用此选项对输入文件进行签名：即将其颁发者名称设置为CA的主题名称，并使用CAs私钥进行数字签名。
此选项通常与-req选项组合。 没有-req选项，输入是必须是自签名的证书。
=item B<-CAkey filename>
sets the CA private key to sign a certificate with. If this option is
not specified then it is assumed that the CA private key is present in
the CA certificate file.
设置CA私钥以签署证书。 如果未指定此选项，则假定CA私钥存在于CA证书文件中。
=item B<-CAserial filename>
sets the CA serial number file to use.
@@ -395,30 +525,44 @@ an even number of hex digits with the serial number to use. After each
use the serial number is incremented and written out to the file again.
The default filename consists of the CA certificate file base name with
".srl" appended. For example if the CA certificate file is called
".srl" appended. For example if the CA certificate file is called
"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
设置要使用的CA序列号文件。
当-CA选项用于签署证书时，它使用文件中指定的序列号。 该文件包含一行，其中包含使用序列号的偶数十六进制数字。 每次使用后，序列号将增加并再次写入文件。
默认文件名由附加了“.srl”的CA证书文件基础名称组成。 例如，如果CA证书文件被称为“mycacert.pem”，则它希望找到一个名为“mycacert.srl”的序列号文件。
=item B<-CAcreateserial>
with this option the CA serial number file is created if it does not exist:
it will contain the serial number "02" and the certificate being signed will
have the 1 as its serial number. Normally if the B<-CA> option is specified
and the serial number file does not exist it is an error.
have the 1 as its serial number. If the B<-CA> option is specified
and the serial number file does not exist a random number is generated;
this is the recommended practice.
使用此选项，CA序列号文件不存在时将被创建：它将包含序列号“02”，正在签名的证书将具有1作为其序列号。
如果指定了-CA选项，并且序列号文件不存在，则生成随机数; 这是推荐的做法。
=item B<-extfile filename>
file containing certificate extensions to use. If not specified then
no extensions are added to the certificate.
包含要使用的证书扩展名的文件。 如果未指定，则不会将任何扩展名添加到证书。
=item B<-extensions section>
the section to add certificate extensions from. If this option is not
specified then the extensions should either be contained in the unnamed
(default) section or the default section should contain a variable called
"extensions" which contains the section to use. See the
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
L<x509v3_config(5)> manual page for details of the
extension section format.
从中添加证书扩展的部分。 如果未指定此选项，则扩展名应包含在未命名（默认）部分中，默认部分应包含一个名为“extensions”的变量，该变量包含要使用的部分。 有关扩展部分格式的详细信息，请参阅x509v3_config（5）手册页。
=item B<-force_pubkey key>
when a certificate is created set its public key to B<key> instead of the
@@ -428,21 +572,31 @@ example DH.
The format or B<key> can be specified using the B<-keyform> option.
当创建证书时，将其公钥设置为key而不是证书或证书请求中的密钥。 此选项对于创建证书，在算法无法正常签署请求时很有用，例如DH。
可以使用-keyform选项指定格式或key。
=back
=head2 NAME OPTIONS
=head2 Name Options
The B<nameopt> command line switch determines how the subject and issuer
names are displayed. If no B<nameopt> switch is present the default "oneline"
format is used which is compatible with previous versions of OpenSSL.
format is used which is compatible with previous versions of GmSSL.
Each option is described in detail below, all options can be preceded by
a B<-> to turn the option off. Only the first four will normally be used.
nameopt命令行开关确定主题和发行者名称的显示方式。 如果没有nameopt开关，
则使用与以前版本的GmSSL兼容的默认“oneline”格式。 每个选项在下面详细描述，
所有选项都可以在前面 - 关闭该选项。 通常只会使用前四个。
=over 4
=item B<compat>
use the old format. This is equivalent to specifying no name options at all.
use the old format.
使用旧的格式。
=item B<RFC2253>
@@ -450,24 +604,41 @@ displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
B<sep_comma_plus>, B<dn_rev> and B<sname>.
显示与esc2253，esc_ctrl，esc_msb，utf8，dump_nostr，dump_unknown，dump_der，sep_comma_plus，
dn_rev和sname等效的RFC2253兼容的名称。
=item B<oneline>
a oneline format which is more readable than RFC2253. It is equivalent to
specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
options.
options. This is the I<default> of no name options are given explicitly.
一种比RFC2253更可读的在线格式。 相当于指定esc_2253，esc_ctrl，esc_msb，utf8，dump_nostr，
dump_der，use_quote，sep_comma_plus_space，space_eq和sname选项。 这是默认的，没有明确给出名称选项。
=item B<multiline>
a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
B<space_eq>, B<lname> and B<align>.
多行格式。 它等效于esc_ctrl，esc_msb，sep_multiline，space_eq，lname和align。
=item B<esc_2253>
escape the "special" characters required by RFC2253 in a field That is
escape the "special" characters required by RFC2253 in a field. That is
B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
and a space character at the beginning or end of a string.
在一个字段中转义RFC2253所需的“特殊”字符。 也就是说，+“<>;另外＃在字符串的开始处转义，在字符串的开头或结尾放置一个空格。
=item B<esc_2254>
escape the "special" characters required by RFC2254 in a field. That is
the B<NUL> character as well as and B<()*>.
在一个字段中转义RFC2254所需的“特殊”字符。 那就是NUL字符以及（）*。
=item B<esc_ctrl>
escape control characters. That is those with ASCII values less than
@@ -475,16 +646,22 @@ escape control characters. That is those with ASCII values less than
RFC2253 \XX notation (where XX are two hex digits representing the
character value).
转义控制字符。 那是ASCII值小于0x20（空格）和删除（0x7f）字符的那些。 它们使用RFC2253 \ XX符号进行转义（其中XX是表示字符值的两个十六进制数字）。
=item B<esc_msb>
escape characters with the MSB set, that is with ASCII values larger than
127.
转义字符与MSB集合，即ASCII值大于127。
=item B<use_quote>
escapes some characters by surrounding the whole string with B<"> characters,
without the option all escaping is done with the B<\> character.
通过围绕整个字符串以“字符”转义一些字符，而没有选项，所有的转义都是用\字符完成的。
=item B<utf8>
convert all strings to UTF8 format first. This is required by RFC2253. If
@@ -496,6 +673,11 @@ using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
Also if this option is off any UTF8Strings will be converted to their
character form first.
首先将所有字符串转换为UTF8格式。 这是RFC2253所要求的。 如果您足够有足够的UTF8兼容终端，
则使用此选项（而不是设置esc_msb）可能会导致多字节（国际）字符的正确显示。 此选项不存在，
则大于0xff的多字节字符将使用格式\ UXXXX（16位）和\ WXXXXXXXX（32位）来表示。 此外，
如果此选项关闭，任何UTF8Strings将首先转换为其字符形式。
=item B<ignore_type>
this option does not attempt to interpret multibyte characters in any
@@ -503,11 +685,16 @@ way. That is their content octets are merely dumped as though one octet
represents each character. This is useful for diagnostic purposes but
will result in rather odd looking output.
此选项不会以任何方式尝试解释多字节字符。 这就是他们的内容八位字节只是被转储，
就像一个八位位组代表每个字符一样。 这对于诊断目的是有用的，但会导致相当奇怪的输出。
=item B<show_type>
show the type of the ASN1 character string. The type precedes the
field contents. For example "BMPSTRING: Hello World".
显示ASN1字符串的类型。 该类型位于字段内容之前。 例如“BMPSTRING：Hello World”。
=item B<dump_der>
when this option is set any fields that need to be hexdumped will
@@ -515,20 +702,30 @@ be dumped using the DER encoding of the field. Otherwise just the
content octets will be displayed. Both options use the RFC2253
B<#XXXX...> format.
当设置此选项时，需要使用hexdumped的任何字段将使用字段的DER编码进行转储。
否则只会显示内容八位字节。 两种选项都使用RFC2253 #XXXX ...格式
=item B<dump_nostr>
dump non character string types (for example OCTET STRING) if this
option is not set then non character string types will be displayed
as though each content octet represents a single character.
转储非字符串类型（例如OCTET STRING），如果未设置此选项，
则将显示非字符串类型，因为每个内容字节表示单个字符。
=item B<dump_all>
dump all fields. This option when used with B<dump_der> allows the
DER encoding of the structure to be unambiguously determined.
转储所有字段。 当与dump_der一起使用时，该选项允许明确地确定结构的DER编码。
=item B<dump_unknown>
dump any field whose OID is not recognised by OpenSSL.
dump any field whose OID is not recognised by GmSSL.
转储GmSSL不识别其OID的任何字段。
=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
B<sep_multiline>
@@ -542,12 +739,18 @@ the RDN separator and a spaced B<+> for the AVA separator. It also
indents the fields by four characters. If no field separator is specified
then B<sep_comma_plus_space> is used by default.
这些选项决定了字段分隔符。 第一个字符在RDN之间，而第二个是多个AVA之间（多个AVA非常罕见，并且不鼓励使用它们）。
以“空格”结尾的选项还会在分隔符之后放置一个空格，使其更易于阅读。 sep_multiline对RDN分隔符使用换行字符，
并为AVA分隔符使用间隔的+。 它还将字段缩小四个字符。 如果没有指定字段分隔符，则默认使用sep_comma_plus_space。
=item B<dn_rev>
reverse the fields of the DN. This is required by RFC2253. As a side
effect this also reverses the order of multiple AVAs but this is
permissible.
反转DN的字段。 这是RFC2253所要求的。 作为副作用，这也反转了多个AVA的顺序，但这是允许的。
=item B<nofname>, B<sname>, B<lname>, B<oid>
these options alter how the field name is displayed. B<nofname> does
@@ -556,19 +759,27 @@ not display the field at all. B<sname> uses the "short name" form
B<oid> represents the OID in numerical form and is useful for
diagnostic purpose.
这些选项会改变字段名称的显示方式。 nofname根本不显示字段。
sname使用“短名称”表单（例如，用于commonName的CN）。
lname使用长格式。 oid以数字形式表示OID，可用于诊断目的。
=item B<align>
align field values for a more readable output. Only usable with
B<sep_multiline>.
调整字段值以获得更可读的输出。 仅适用于sep_multiline。
=item B<space_eq>
places spaces round the B<=> character which follows the field
name.
在字段名后面的=字符上放置空格。
=back
=head2 TEXT OPTIONS
=head2 Text Options
As well as customising the name output format, it is also possible to
customise the actual fields printed using the B<certopt> options when
@@ -654,59 +865,59 @@ line.
Display the contents of a certificate:
openssl x509 -in cert.pem -noout -text
gmssl x509 -in cert.pem -noout -text
Display the certificate serial number:
openssl x509 -in cert.pem -noout -serial
gmssl x509 -in cert.pem -noout -serial
Display the certificate subject name:
openssl x509 -in cert.pem -noout -subject
gmssl x509 -in cert.pem -noout -subject
Display the certificate subject name in RFC2253 form:
openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
gmssl x509 -in cert.pem -noout -subject -nameopt RFC2253
Display the certificate subject name in oneline form on a terminal
supporting UTF8:
openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
gmssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
Display the certificate MD5 fingerprint:
openssl x509 -in cert.pem -noout -fingerprint
gmssl x509 -in cert.pem -noout -fingerprint
Display the certificate SHA1 fingerprint:
openssl x509 -sha1 -in cert.pem -noout -fingerprint
gmssl x509 -sha1 -in cert.pem -noout -fingerprint
Convert a certificate from PEM to DER format:
openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
gmssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
Convert a certificate to a certificate request:
openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
gmssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
Convert a certificate request into a self signed certificate using
extensions for a CA:
openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
-signkey key.pem -out cacert.pem
gmssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
-signkey key.pem -out cacert.pem
Sign a certificate request using the CA certificate above and add user
certificate extensions:
openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
-CA cacert.pem -CAkey key.pem -CAcreateserial
gmssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
-CA cacert.pem -CAkey key.pem -CAcreateserial
Set a certificate to be trusted for SSL client use and change set its alias to
"Steve's Class 1 CA"
openssl x509 -in cert.pem -addtrust clientAuth \
-setalias "Steve's Class 1 CA" -out trust.pem
gmssl x509 -in cert.pem -addtrust clientAuth \
-setalias "Steve's Class 1 CA" -out trust.pem
=head1 NOTES
@@ -821,7 +1032,7 @@ Otherwise it is the same as a normal SSL server.
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or should have the
S/MIME bit set. If the S/MIME bit is not set in netscape certificate type
S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type
then the SSL client bit is tolerated as an alternative but a warning is shown:
this is because some Verisign certificates don't set the S/MIME bit.
@@ -840,7 +1051,7 @@ if the keyUsage extension is present.
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or must have the
S/MIME CA bit set: this is used as a work around if the basicConstraints
extension is absent.
extension is absent.
=item B<CRL Signing>
@@ -866,25 +1077,27 @@ be checked.
There should be options to explicitly set such things as start and end
dates rather than an offset from the current time.
The code to implement the verify behaviour described in the B<TRUST SETTINGS>
is currently being developed. It thus describes the intended behaviour rather
than the current behaviour. It is hoped that it will represent reality in
OpenSSL 0.9.5 and later.
=head1 SEE ALSO
L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>,
L<x509v3_config(5)|x509v3_config(5)>
L<req(1)>, L<ca(1)>, L<genrsa(1)>,
L<gendsa(1)>, L<verify(1)>,
L<x509v3_config(5)>
=head1 HISTORY
Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
of the distinguished name. In OpenSSL 1.0.0 and later it is based on a
before GmSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
of the distinguished name. In GmSSL 1.0.0 and later it is based on a
canonical version of the DN using SHA1. This means that any directories using
the old form must have their links rebuilt using B<c_rehash> or similar.
the old form must have their links rebuilt using B<c_rehash> or similar.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

90
doc/apps/x509v3_config.pod
View File

@@ -1,6 +1,8 @@
=pod
=for comment openssl_manual_section:5
=encoding utf8
=for comment gmssl_manual_section:5
=head1 NAME
@@ -8,7 +10,7 @@ x509v3_config - X509 V3 certificate extension configuration format
=head1 DESCRIPTION
Several of the OpenSSL utilities can add extensions to a certificate or
Several of the GmSSL utilities can add extensions to a certificate or
certificate request based on the contents of a configuration file.
Typically the application will contain an option to point to an extension
@@ -88,7 +90,7 @@ only be used to sign end user certificates and not further CAs.
Key usage is a multi valued extension consisting of a list of names of the
permitted key usages.
The supporte names are: digitalSignature, nonRepudiation, keyEncipherment,
The supported names are: digitalSignature, nonRepudiation, keyEncipherment,
dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
and decipherOnly.
@@ -108,24 +110,24 @@ These can either be object short names or the dotted numerical form of OIDs.
While any OID can be used only certain values make sense. In particular the
following PKIX, NS and MS values are meaningful:
Value Meaning
----- -------
serverAuth SSL/TLS Web Server Authentication.
clientAuth SSL/TLS Web Client Authentication.
codeSigning Code signing.
emailProtection E-mail Protection (S/MIME).
timeStamping Trusted Timestamping
msCodeInd Microsoft Individual Code Signing (authenticode)
msCodeCom Microsoft Commercial Code Signing (authenticode)
msCTLSign Microsoft Trust List Signing
msSGC Microsoft Server Gated Crypto
msEFS Microsoft Encrypted File System
nsSGC Netscape Server Gated Crypto
Value Meaning
----- -------
serverAuth SSL/TLS Web Server Authentication.
clientAuth SSL/TLS Web Client Authentication.
codeSigning Code signing.
emailProtection E-mail Protection (S/MIME).
timeStamping Trusted Timestamping
OCSPSigning OCSP Signing
ipsecIKE ipsec Internet Key Exchange
msCodeInd Microsoft Individual Code Signing (authenticode)
msCodeCom Microsoft Commercial Code Signing (authenticode)
msCTLSign Microsoft Trust List Signing
msEFS Microsoft Encrypted File System
Examples:
extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=nsSGC,msSGC
extendedKeyUsage=serverAuth,clientAuth
=head2 Subject Key Identifier.
@@ -178,7 +180,7 @@ prefacing the name with a B<+> character.
otherName can include arbitrary data associated with an OID: the value
should be the OID followed by a semicolon and the content in standard
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format.
L<ASN1_generate_nconf(3)> format.
Examples:
@@ -202,7 +204,7 @@ Examples:
The issuer alternative name option supports all the literal options of
subject alternative name. It does B<not> support the email:copy option because
that would not make sense. It does support an additional issuer:copy option
that will copy all the subject alternative name values from the issuer
that will copy all the subject alternative name values from the issuer
certificate (if possible).
Example:
@@ -224,7 +226,7 @@ Example:
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
=head2 CRL distribution points.
=head2 CRL distribution points
This is a multi-valued extension whose options can be either in name:value pair
using the same form as subject alternative name or a single value representing
@@ -358,7 +360,7 @@ Some software (for example some versions of MSIE) may require ia5org.
=head2 Policy Constraints
This is a multi-valued extension which consisting of the names
B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger
B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
value. At least one component must be present.
Example:
@@ -380,7 +382,7 @@ Example:
The name constraints extension is a multi-valued extension. The name should
begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
the name and the value follows the syntax of subjectAltName except email:copy
is not supported and the B<IP> form should consist of an IP addresses and
is not supported and the B<IP> form should consist of an IP addresses and
subnet mask separated by a B</>.
Examples:
@@ -401,6 +403,20 @@ Example:
noCheck = ignored
=head2 TLS Feature (aka Must Staple)
This is a multi-valued extension consisting of a list of TLS extension
identifiers. Each identifier may be a number (0..65535) or a supported name.
When a TLS client sends a listed extension, the TLS server is expected to
include that extension in its reply.
The supported names are: B<status_request> and B<status_request_v2>.
Example:
tlsfeature = status_request
=head1 DEPRECATED EXTENSIONS
The following extensions are non standard, Netscape specific and largely
@@ -433,7 +449,7 @@ B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
=head1 ARBITRARY EXTENSIONS
If an extension is not supported by the OpenSSL code then it must be encoded
If an extension is not supported by the GmSSL code then it must be encoded
using the arbitrary extension format. It is also possible to use the arbitrary
format for supported extensions. Extreme care should be taken to ensure that
the data is formatted correctly for the given extension type.
@@ -441,7 +457,7 @@ the data is formatted correctly for the given extension type.
There are two ways to encode arbitrary extensions.
The first way is to use the word ASN1 followed by the extension content
using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>.
using the same syntax as L<ASN1_generate_nconf(3)>.
For example:
1.2.3.4=critical,ASN1:UTF8String:Some random data
@@ -491,9 +507,9 @@ will produce an error but the equivalent form:
[subject_alt_section]
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
is valid.
is valid.
Due to the behaviour of the OpenSSL B<conf> library the same field name
Due to the behaviour of the GmSSL B<conf> library the same field name
can only occur once in a section. This means that:
subjectAltName=@alt_section
@@ -510,20 +526,18 @@ will only recognize the last value. This can be worked around by using the form:
email.1=steve@here
email.2=steve@there
=head1 HISTORY
The X509v3 extension code was first added to OpenSSL 0.9.2.
Policy mappings, inhibit any policy and name constraints support was added in
OpenSSL 0.9.8
The B<directoryName> and B<otherName> option as well as the B<ASN1> option
for arbitrary extensions was added in OpenSSL 0.9.8
=head1 SEE ALSO
L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>,
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
L<req(1)>, L<ca(1)>, L<x509(1)>,
L<ASN1_generate_nconf(3)>
=head1 COPYRIGHT
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the GmSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/c-indentation.el
View File

@@ -1,45 +0,0 @@
; This Emacs Lisp file defines a C indentation style that closely
; follows most aspects of the one that is used throughout SSLeay,
; and hence in OpenSSL.
;
; This definition is for the "CC mode" package, which is the default
; mode for editing C source files in Emacs 20, not for the older
; c-mode.el (which was the default in less recent releaes of Emacs 19).
;
; Copy the definition in your .emacs file or use M-x eval-buffer.
; To activate this indentation style, visit a C file, type
; M-x c-set-style <RET> (or C-c . for short), and enter "eay".
; To toggle the auto-newline feature of CC mode, type C-c C-a.
;
; Apparently statement blocks that are not introduced by a statement
; such as "if" and that are not the body of a function cannot
; be handled too well by CC mode with this indentation style,
; so you have to indent them manually (you can use C-q tab).
;
; For suggesting improvements, please send e-mail to bodo@openssl.org.
(c-add-style "eay"
'((c-basic-offset . 8)
(indent-tabs-mode . t)
(c-comment-only-line-offset . 0)
(c-hanging-braces-alist)
(c-offsets-alist . ((defun-open . +)
(defun-block-intro . 0)
(class-open . +)
(class-close . +)
(block-open . 0)
(block-close . 0)
(substatement-open . +)
(statement . 0)
(statement-block-intro . 0)
(statement-case-open . +)
(statement-case-intro . +)
(case-label . -)
(label . -)
(arglist-cont-nonempty . +)
(topmost-intro . -)
(brace-list-close . 0)
(brace-list-intro . 0)
(brace-list-open . +)
))))

20
doc/crypto/ASN1_OBJECT_new.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
=head1 SYNOPSIS
@@ -16,9 +18,10 @@ ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
The ASN1_OBJECT allocation routines, allocate and free an
ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure.
ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
If B<a> is NULL, nothing is done.
=head1 NOTES
@@ -29,17 +32,22 @@ such as OBJ_nid2obj() are used instead.
=head1 RETURN VALUES
If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
code that can be obtained by L<ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
ASN1_OBJECT_free() returns no value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)>
L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)>
=head1 HISTORY
=head1 COPYRIGHT
ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL.
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

34
doc/crypto/ASN1_STRING_length.pod
View File

@@ -1,16 +1,19 @@
=pod
=encoding utf8
=head1 NAME
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 -
ASN1_STRING utility functions
ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_length(ASN1_STRING *x);
const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);
ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
@@ -19,9 +22,9 @@ ASN1_STRING utility functions
int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
int ASN1_STRING_type(ASN1_STRING *x);
int ASN1_STRING_type(const ASN1_STRING *x);
int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
=head1 DESCRIPTION
@@ -29,10 +32,14 @@ These functions allow an B<ASN1_STRING> structure to be manipulated.
ASN1_STRING_length() returns the length of the content of B<x>.
ASN1_STRING_data() returns an internal pointer to the data of B<x>.
ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
Since this is an internal pointer it should B<not> be freed or
modified in any way.
ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the
returned value is not constant. This function is deprecated:
applications should use ASN1_STRING_get0_data() instead.
ASN1_STRING_dup() returns a copy of the structure B<a>.
ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
@@ -48,12 +55,12 @@ such as B<V_ASN1_OCTET_STRING>.
ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
converted data is allocated in a buffer in B<*out>. The length of
B<out> is returned or a negative error code. The buffer B<*out>
should be free using OPENSSL_free().
should be freed using OPENSSL_free().
=head1 NOTES
Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
structure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed
structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed
to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.
B<ASN1_STRING> is also used for some B<CHOICE> types which consist
entirely of primitive string types such as B<DirectoryString> and
@@ -72,12 +79,17 @@ character in big endian format, UTF8String will be in UTF8 format.
Similar care should be take to ensure the data is in the correct format
when calling ASN1_STRING_set().
=head1 RETURN VALUES
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

14
doc/crypto/ASN1_STRING_new.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -
@@ -22,6 +24,7 @@ ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
type B<type>.
ASN1_STRING_free() frees up B<a>.
If B<a> is NULL nothing is done.
=head1 NOTES
@@ -37,10 +40,15 @@ ASN1_STRING_free() does not return a value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
TBA
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

27
doc/crypto/ASN1_STRING_print_ex.pod
View File

@@ -1,16 +1,18 @@
=pod
=encoding utf8
=head1 NAME
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines.
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, ASN1_STRING *str);
int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, const ASN1_STRING *str);
=head1 DESCRIPTION
@@ -30,7 +32,7 @@ with '.'.
ASN1_STRING_print() is a legacy function which should be avoided in new applications.
Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
The complete set of supported options for B<flags> is listed below.
@@ -75,7 +77,7 @@ Normally non character string types (such as OCTET STRING) are assumed to be
one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will
be dumped instead.
When a type is dumped normally just the content octets are printed, if
When a type is dumped normally just the content octets are printed, if
B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
instead (including tag and length octets).
@@ -86,11 +88,16 @@ equivalent to:
=head1 SEE ALSO
L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)|ASN1_tag2str(3)>
L<X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)>
=head1 HISTORY
=head1 COPYRIGHT
TBA
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/crypto/ASN1_TIME_set.pod
View File

@@ -1,9 +1,11 @@
=pod
=encoding utf8
=head1 NAME
ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string,
ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions.
ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions
=head1 SYNOPSIS
@@ -100,7 +102,7 @@ Determine if one time is later or sooner than the current time:
int day, sec;
if (!ASN1_TIME_diff(&day, &sec, NULL, to))
/* Invalid time format */
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
@@ -123,7 +125,16 @@ otherwise.
ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if
an error occurred (I/O error or invalid time format).
ASN1_TIME_diff() returns 1 for sucess and 0 for failure. It can fail if the
ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
pass ASN1_TIME structure has invalid syntax for example.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/crypto/ASN1_generate_nconf.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
@@ -8,8 +10,8 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
#include <openssl/asn1.h>
ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
=head1 DESCRIPTION
@@ -19,7 +21,7 @@ in an B<ASN1_TYPE> structure.
B<str> contains the string to encode B<nconf> or B<cnf> contains
the optional configuration information where additional strings
will be read from. B<nconf> will typically come from a config
file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
which will typically be used by X509 v3 certificate extension
functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
configuration will be used.
@@ -40,7 +42,7 @@ That is zero or more comma separated modifiers followed by a type
followed by an optional colon and a value. The formats of B<type>,
B<value> and B<modifier> are explained below.
=head2 SUPPORTED TYPES
=head2 Supported Types
The supported types are listed below. Unless otherwise specified
only the B<ASCII> format is permissible.
@@ -52,7 +54,7 @@ only the B<ASCII> format is permissible.
This encodes a boolean type. The B<value> string is mandatory and
should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
are acceptable.
are acceptable.
=item B<NULL>
@@ -78,12 +80,12 @@ a short name, a long name or numerical format.
=item B<UTCTIME>, B<UTC>
Encodes an ASN1 B<UTCTime> structure, the value should be in
the format B<YYMMDDHHMMSSZ>.
the format B<YYMMDDHHMMSSZ>.
=item B<GENERALIZEDTIME>, B<GENTIME>
Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
the format B<YYYYMMDDHHMMSSZ>.
the format B<YYYYMMDDHHMMSSZ>.
=item B<OCTETSTRING>, B<OCT>
@@ -119,7 +121,7 @@ will be encoded.
=back
=head2 MODIFIERS
=head2 Modifiers
Modifiers affect the following structure, they can be used to
add EXPLICIT or IMPLICIT tagging, add wrappers or to change
@@ -181,7 +183,7 @@ A BITSTRING with bits 1 and 5 set and all others zero:
FORMAT:BITLIST,BITSTRING:1,5
A more complex example using a config file to produce a
SEQUENCE consiting of a BOOL an OID and a UTF8String:
SEQUENCE consisting of a BOOL an OID and a UTF8String:
asn1 = SEQUENCE:seq_section
@@ -252,14 +254,19 @@ structure:
ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes that can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

38
doc/crypto/BIO_ctrl.pod
View File

@@ -1,37 +1,40 @@
=pod
=encoding utf8
=head1 NAME
BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
BIO_get_info_callback, BIO_set_info_callback - BIO control operations
BIO_get_info_callback, BIO_set_info_callback, bio_info_cb
- BIO control operations
=head1 SYNOPSIS
#include <openssl/bio.h>
long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
long BIO_callback_ctrl(BIO *b, int cmd, bio_info_cb cb);
char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
int BIO_reset(BIO *b);
int BIO_seek(BIO *b, int ofs);
int BIO_tell(BIO *b);
int BIO_flush(BIO *b);
int BIO_eof(BIO *b);
int BIO_set_close(BIO *b,long flag);
int BIO_set_close(BIO *b, long flag);
int BIO_get_close(BIO *b);
int BIO_pending(BIO *b);
int BIO_wpending(BIO *b);
size_t BIO_ctrl_pending(BIO *b);
size_t BIO_ctrl_wpending(BIO *b);
int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
int BIO_get_info_callback(BIO *b, bio_info_cb **cbp);
int BIO_set_info_callback(BIO *b, bio_info_cb *cb);
=head1 DESCRIPTION
@@ -94,7 +97,7 @@ return the amount of pending data.
=head1 NOTES
BIO_flush(), because it can write data may return 0 or -1 indicating
that the call should be retried later in a similar manner to BIO_write().
that the call should be retried later in a similar manner to BIO_write_ex().
The BIO_should_retry() call should be used and appropriate action taken
is the call fails.
@@ -121,8 +124,15 @@ operation.
Some of the return values are ambiguous and care should be taken. In
particular a return value of 0 can be returned if an operation is not
supported, if an error occurred, if EOF has not been reached and in
the case of BIO_seek() on a file BIO for a successful operation.
the case of BIO_seek() on a file BIO for a successful operation.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/crypto/BIO_f_base64.pod
View File

@@ -1,15 +1,19 @@
=pod
=encoding utf8
=head1 NAME
BIO_f_base64 - base64 BIO filter
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_base64(void);
const BIO_METHOD *BIO_f_base64(void);
=head1 DESCRIPTION
@@ -17,7 +21,7 @@ BIO_f_base64() returns the base64 BIO method. This is a filter
BIO that base64 encodes any data written through it and decodes
any data read through it.
Base64 BIOs do not support BIO_gets() or BIO_puts().
Base64 BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on a base64 BIO that is being written through is
used to signal that no more data is to be encoded: this is used
@@ -63,8 +67,8 @@ data to standard output:
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_flush(bio_out);
BIO_free_all(b64);
@@ -77,6 +81,13 @@ data following the base64 encoded block to be misinterpreted.
There should be some way of specifying a test that the BIO can perform
to reliably determine EOF (for example a MIME boundary).
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

46
doc/crypto/BIO_f_buffer.pod
View File

@@ -1,20 +1,28 @@
=pod
=encoding utf8
=head1 NAME
BIO_f_buffer - buffering BIO
BIO_get_buffer_num_lines,
BIO_set_read_buffer_size,
BIO_set_write_buffer_size,
BIO_set_buffer_size,
BIO_set_buffer_read_data,
BIO_f_buffer
- buffering BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_f_buffer(void);
const BIO_METHOD *BIO_f_buffer(void);
#define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL)
#define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0)
#define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1)
#define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL)
#define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf)
long BIO_get_buffer_num_lines(BIO *b);
long BIO_set_read_buffer_size(BIO *b, long size);
long BIO_set_write_buffer_size(BIO *b, long size);
long BIO_set_buffer_size(BIO *b, long size);
long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
=head1 DESCRIPTION
@@ -41,6 +49,8 @@ is expanded.
=head1 NOTES
These functions, other than BIO_f_buffer(), are implemented as macros.
Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
possible to provide BIO_gets() functionality if the following BIOs do not
@@ -66,9 +76,19 @@ there was an error.
=head1 SEE ALSO
L<BIO(3)|BIO(3)>,
L<BIO_reset(3)|BIO_reset(3)>,
L<BIO_flush(3)|BIO_flush(3)>,
L<BIO_pop(3)|BIO_pop(3)>,
L<BIO_ctrl(3)|BIO_ctrl(3)>,
L<BIO_int_ctrl(3)|BIO_ctrl(3)>
L<BIO(3)>,
L<BIO_reset(3)>,
L<BIO_flush(3)>,
L<BIO_pop(3)>,
L<BIO_ctrl(3)>.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

25
doc/crypto/BIO_f_cipher.pod
View File

@@ -1,17 +1,21 @@
=pod
=encoding utf8
=head1 NAME
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_cipher(void);
void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
const BIO_METHOD *BIO_f_cipher(void);
void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
int BIO_get_cipher_status(BIO *b)
int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
@@ -22,7 +26,7 @@ BIO that encrypts any data written through it, and decrypts any data
read from it. It is a BIO wrapper for the cipher routines
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
Cipher BIOs do not support BIO_gets() or BIO_puts().
Cipher BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on an encryption BIO that is being written through is
used to signal that no more data is to be encrypted: this is used
@@ -48,7 +52,7 @@ When encrypting BIO_flush() B<must> be called to flush the final block
through the BIO. If it is not then the final block will fail a subsequent
decrypt.
When decrypting an error on the final block is signalled by a zero
When decrypting an error on the final block is signaled by a zero
return value from the read operation. A successful decrypt followed
by EOF will also return zero for the final read. BIO_get_cipher_status()
should be called to determine if the decrypt was successful.
@@ -67,10 +71,13 @@ for failure.
BIO_get_cipher_ctx() currently always returns 1.
=head1 EXAMPLES
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 SEE ALSO
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
TBA
=cut

58
doc/crypto/BIO_f_md.pod
View File

@@ -1,18 +1,22 @@
=pod
=encoding utf8
=head1 NAME
BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_md(void);
int BIO_set_md(BIO *b,EVP_MD *md);
int BIO_get_md(BIO *b,EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
const BIO_METHOD *BIO_f_md(void);
int BIO_set_md(BIO *b, EVP_MD *md);
int BIO_get_md(BIO *b, EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
=head1 DESCRIPTION
@@ -58,10 +62,8 @@ If an application needs to call BIO_gets() or BIO_puts() through
a chain containing digest BIOs then this can be done by prepending
a buffering BIO.
Before OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO
had been initialized for example by calling BIO_set_md() ). In OpenSSL
1.0.0 and later the context is always returned and the BIO is state is set
to initialized. This allows applications to initialize the context externally
Calling BIO_get_md_ctx() will return the context and initialize the BIO
state. This allows applications to initialize the context externally
if the standard calls such as BIO_set_md() are not sufficiently flexible.
=head1 RETURN VALUES
@@ -105,9 +107,9 @@ The next example digests data by reading through a chain instead:
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
do {
rdlen = BIO_read(bio, buf, sizeof(buf));
rdlen = BIO_read(bio, buf, sizeof(buf));
/* Might want to do something with the data here */
} while(rdlen > 0);
} while (rdlen > 0);
This next example retrieves the message digests from a BIO chain and
outputs them. This could be used with the examples above.
@@ -116,18 +118,18 @@ outputs them. This could be used with the examples above.
unsigned char mdbuf[EVP_MAX_MD_SIZE];
int mdlen;
int i;
mdtmp = bio; /* Assume bio has previously been set up */
mdtmp = bio; /* Assume bio has previously been set up */
do {
EVP_MD *md;
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if(!mdtmp) break;
BIO_get_md(mdtmp, &md);
EVP_MD *md;
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if (!mdtmp) break;
BIO_get_md(mdtmp, &md);
printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while(mdtmp);
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while (mdtmp);
BIO_free_all(bio);
@@ -139,6 +141,18 @@ and BIO_puts() should be passed to the next BIO in the chain and digest
the data passed through and that digests should be retrieved using a
separate BIO_ctrl() call.
=head1 SEE ALSO
=head1 HISTORY
TBA
Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the
BIO was initialized first.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BIO_f_null.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BIO_f_null - null filter
@@ -8,7 +10,7 @@ BIO_f_null - null filter
#include <openssl/bio.h>
BIO_METHOD * BIO_f_null(void);
const BIO_METHOD * BIO_f_null(void);
=head1 DESCRIPTION
@@ -27,6 +29,13 @@ As may be apparent a null filter BIO is not particularly useful.
BIO_f_null() returns the null filter BIO method.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

222
doc/crypto/BIO_f_ssl.pod
View File

@@ -1,42 +1,45 @@
=pod
=encoding utf8
=head1 NAME
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
BIO_do_handshake,
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
BIO_ssl_shutdown - SSL BIO
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>
BIO_METHOD *BIO_f_ssl(void);
const BIO_METHOD *BIO_f_ssl(void);
#define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
#define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
#define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
#define BIO_set_ssl_renegotiate_bytes(b,num) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
#define BIO_set_ssl_renegotiate_timeout(b,seconds) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
#define BIO_get_num_renegotiates(b) \
BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
long BIO_set_ssl(BIO *b, SSL *ssl, long c);
long BIO_get_ssl(BIO *b, SSL **sslp);
long BIO_set_ssl_mode(BIO *b, long client);
long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
long BIO_get_num_renegotiates(BIO *b);
BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
int BIO_ssl_copy_session_id(BIO *to,BIO *from);
int BIO_ssl_copy_session_id(BIO *to, BIO *from);
void BIO_ssl_shutdown(BIO *bio);
#define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
long BIO_do_handshake(BIO *b);
=head1 DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
SSL I/O.
SSL I/O.
I/O performed on an SSL BIO communicates using the SSL protocol with
the SSLs read and write BIOs. If an SSL connection is not established
@@ -63,7 +66,7 @@ BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
is 1 client mode is set. If B<client> is 0 server mode is set.
BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
to B<num>. When set after every B<num> bytes of I/O (read and write)
to B<num>. When set after every B<num> bytes of I/O (read and write)
the SSL session is automatically renegotiated. B<num> must be at
least 512 bytes.
@@ -84,7 +87,7 @@ BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
BIO.
BIO_ssl_copy_session_id() copies an SSL session id between
BIO_ssl_copy_session_id() copies an SSL session id between
BIO chains B<from> and B<to>. It does this by locating the
SSL BIOs in each chain and calling SSL_copy_session_id() on
the internal SSL pointer.
@@ -110,7 +113,7 @@ circumstances. Specifically this will happen if a session
renegotiation takes place during a BIO_read() operation, one
case where this happens is when step up occurs.
In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be
The SSL flag SSL_AUTO_RETRY can be
set to disable this behaviour. That is when this flag is set
an SSL BIO using a blocking transport will never request a
retry.
@@ -124,15 +127,15 @@ Applications do not have to call BIO_do_handshake() but may wish
to do so to separate the handshake process from other I/O
processing.
=head1 RETURN VALUES
TBA
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
=head1 EXAMPLE
This SSL/TLS client example, attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
unencrypted example in L<BIO_s_connect(3)>.
BIO *sbio, *out;
int len;
@@ -140,57 +143,48 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* XXX Seed the PRNG if needed. */
/* We would seed the PRNG here if the platform didn't
* do it automatically
*/
ctx = SSL_CTX_new(TLS_client_method());
ctx = SSL_CTX_new(SSLv23_client_method());
/* We'd normally set some stuff like the verify paths and
* mode here because as things stand this will connect to
* any server whose certificate is signed by any CA.
*/
/* XXX Set verify paths and mode here. */
sbio = BIO_new_ssl_connect(ctx);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* We might want to do other things with ssl here */
/* XXX We might want to do other things with ssl here */
BIO_set_conn_hostname(sbio, "localhost:https");
/* An empty host part means the loopback address */
BIO_set_conn_hostname(sbio, ":https");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
if (BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
exit(1);
}
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
/* Could examine ssl here to get connection info */
/* XXX Could examine ssl here to get connection info */
BIO_puts(sbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
for ( ; ; ) {
len = BIO_read(sbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
@@ -206,106 +200,83 @@ a client and also echoes the request to standard output.
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* XXX Seed the PRNG if needed. */
/* Might seed PRNG here */
ctx = SSL_CTX_new(SSLv23_server_method());
if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {
fprintf(stderr, "Error setting up SSL_CTX\n");
ERR_print_errors_fp(stderr);
return 0;
ctx = SSL_CTX_new(TLS_server_method());
if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {
fprintf(stderr, "Error setting up SSL_CTX\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Might do other things here like setting verify locations and
* DH and/or RSA temporary key callbacks
*/
/* XXX Other things like set verify locations, EDH temp callbacks. */
/* New SSL BIO setup as server */
sbio=BIO_new_ssl(ctx,0);
sbio = BIO_new_ssl(ctx, 0);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* Create the buffering BIO */
bbio = BIO_new(BIO_f_buffer());
/* Add to chain */
sbio = BIO_push(bbio, sbio);
acpt = BIO_new_accept("4433");
acpt=BIO_new_accept("4433");
/* By doing this when a new connection is established
/*
* By doing this when a new connection is established
* we automatically have sbio inserted into it. The
* BIO chain is now 'swallowed' by the accept BIO and
* will be freed when the accept BIO is freed.
* will be freed when the accept BIO is freed.
*/
BIO_set_accept_bios(acpt,sbio);
BIO_set_accept_bios(acpt, sbio);
out = BIO_new_fp(stdout, BIO_NOCLOSE);
/* Setup accept BIO */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
return 0;
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Now wait for incoming connection */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
return 0;
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* We only want one connection so remove and free
* accept BIO
*/
/* We only want one connection so remove and free accept BIO */
sbio = BIO_pop(acpt);
BIO_free_all(acpt);
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
return 0;
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
exit(1);
}
BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
BIO_puts(sbio, "--------------------------------------------------\r\n");
for(;;) {
len = BIO_gets(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break;
for ( ; ; ) {
len = BIO_gets(sbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
break;
}
BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "\r\n");
/* Since there is a buffering BIO present we had better flush it */
BIO_flush(sbio);
BIO_free_all(sbio);
=head1 BUGS
@@ -317,6 +288,13 @@ explicitly being popped (e.g. a pop higher up the chain). Applications which
included workarounds for this bug (e.g. freeing BIOs more than once) should
be modified to handle this fix or they may free up an already freed BIO.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

79
doc/crypto/BIO_find_type.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
@@ -8,46 +10,23 @@ BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
#include <openssl/bio.h>
BIO * BIO_find_type(BIO *b,int bio_type);
BIO * BIO_next(BIO *b);
#define BIO_method_type(b) ((b)->method->type)
#define BIO_TYPE_NONE 0
#define BIO_TYPE_MEM (1|0x0400)
#define BIO_TYPE_FILE (2|0x0400)
#define BIO_TYPE_FD (4|0x0400|0x0100)
#define BIO_TYPE_SOCKET (5|0x0400|0x0100)
#define BIO_TYPE_NULL (6|0x0400)
#define BIO_TYPE_SSL (7|0x0200)
#define BIO_TYPE_MD (8|0x0200)
#define BIO_TYPE_BUFFER (9|0x0200)
#define BIO_TYPE_CIPHER (10|0x0200)
#define BIO_TYPE_BASE64 (11|0x0200)
#define BIO_TYPE_CONNECT (12|0x0400|0x0100)
#define BIO_TYPE_ACCEPT (13|0x0400|0x0100)
#define BIO_TYPE_PROXY_CLIENT (14|0x0200)
#define BIO_TYPE_PROXY_SERVER (15|0x0200)
#define BIO_TYPE_NBIO_TEST (16|0x0200)
#define BIO_TYPE_NULL_FILTER (17|0x0200)
#define BIO_TYPE_BER (18|0x0200)
#define BIO_TYPE_BIO (19|0x0400)
#define BIO_TYPE_DESCRIPTOR 0x0100
#define BIO_TYPE_FILTER 0x0200
#define BIO_TYPE_SOURCE_SINK 0x0400
BIO *BIO_find_type(BIO *b, int bio_type);
BIO *BIO_next(BIO *b);
int BIO_method_type(const BIO *b);
=head1 DESCRIPTION
The BIO_find_type() searches for a BIO of a given type in a chain, starting
at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search
at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search
is made for a BIO of that type. If B<type> is a general type (such as
B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
searched for. BIO_find_type() returns the next matching BIO or NULL if none is
found.
Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations.
The following general types are defined:
B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
For a list of the specific types, see the B<openssl/bio.h> header file.
BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
@@ -63,36 +42,30 @@ BIO_next() returns the next BIO in a chain.
BIO_method_type() returns the type of the BIO B<b>.
=head1 NOTES
BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO
chain or find multiple matches using BIO_find_type(). Previous versions had to
use:
next = bio->next_bio;
=head1 BUGS
BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a
NULL pointer for the B<b> argument.
=head1 EXAMPLE
Traverse a chain looking for digest BIOs:
BIO *btmp;
btmp = in_bio; /* in_bio is chain to search through */
btmp = in_bio; /* in_bio is chain to search through */
do {
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if(btmp == NULL) break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if (btmp == NULL) break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...
btmp = BIO_next(btmp);
} while(btmp);
btmp = BIO_next(btmp);
} while (btmp);
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

49
doc/crypto/BIO_new.pod
View File

@@ -1,58 +1,60 @@
=pod
=encoding utf8
=head1 NAME
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions
BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all,
BIO_set - BIO allocation and freeing functions
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_new(BIO_METHOD *type);
int BIO_set(BIO *a,BIO_METHOD *type);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
BIO * BIO_new(const BIO_METHOD *type);
int BIO_set(BIO *a, const BIO_METHOD *type);
int BIO_up_ref(BIO *a);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
=head1 DESCRIPTION
The BIO_new() function returns a new BIO using method B<type>.
BIO_set() sets the method of an already existing BIO.
BIO_up_ref() increments the reference count associated with the BIO object.
BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
but it does not return a value. Calling BIO_free() may also have some effect
but it does not return a value.
If B<a> is NULL nothing is done.
Calling BIO_free() may also have some effect
on the underlying I/O structure, for example it may close the file being
referred to under certain circumstances. For more details see the individual
BIO_METHOD descriptions.
BIO_free_all() frees up an entire BIO chain, it does not halt if an error
occurs freeing up an individual BIO in the chain.
If B<a> is NULL nothing is done.
=head1 RETURN VALUES
BIO_new() returns a newly created BIO or NULL if the call fails.
BIO_set(), BIO_free() return 1 for success and 0 for failure.
BIO_set(), BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.
BIO_free_all() and BIO_vfree() do not return values.
=head1 NOTES
Some BIOs (such as memory BIOs) can be used immediately after calling
BIO_new(). Others (such as file BIOs) need some additional initialization,
and frequently a utility function exists to create and initialize such BIOs.
If BIO_free() is called on a BIO chain it will only free one BIO resulting
in a memory leak.
Calling BIO_free_all() a single BIO has the same effect as calling BIO_free()
Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free()
on it other than the discarded return value.
Normally the B<type> argument is supplied by a function which returns a
pointer to a BIO_METHOD. There is a naming convention for such functions:
a source/sink BIO is normally called BIO_s_*() and a filter BIO
BIO_f_*();
=head1 HISTORY
BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
=head1 EXAMPLE
@@ -60,6 +62,13 @@ Create a memory BIO:
BIO *mem = BIO_new(BIO_s_mem());
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/crypto/BIO_new_CMS.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BIO_new_CMS - CMS streaming filter BIO
BIO_new_CMS - CMS streaming filter BIO
=head1 SYNOPSIS
@@ -56,11 +58,20 @@ occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_encrypt(3)|CMS_encrypt(3)>
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 HISTORY
BIO_new_CMS() was added to OpenSSL 1.0.0
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

30
doc/crypto/BIO_push.pod
View File

@@ -1,15 +1,18 @@
=pod
=encoding utf8
=head1 NAME
BIO_push, BIO_pop - add and remove BIOs from a chain.
BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_push(BIO *b,BIO *append);
BIO * BIO_pop(BIO *b);
BIO *BIO_push(BIO *b, BIO *append);
BIO *BIO_pop(BIO *b);
void BIO_set_next(BIO *b, BIO *next);
=head1 DESCRIPTION
@@ -21,6 +24,10 @@ in the chain, or NULL if there is no next BIO. The removed BIO then
becomes a single BIO with no association with the original chain,
it can thus be freed or attached to a different chain.
BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
by B<next>. The new chain may include some of the same BIOs from the old chain
or it may be completely different.
=head1 NOTES
The names of these functions are perhaps a little misleading. BIO_push()
@@ -66,4 +73,19 @@ BIO.
=head1 SEE ALSO
TBA
L<bio>
=head1 HISTORY
The BIO_set_next() function was added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

37
doc/crypto/BIO_read.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
@@ -8,10 +10,10 @@ BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
#include <openssl/bio.h>
int BIO_read(BIO *b, void *buf, int len);
int BIO_gets(BIO *b, char *buf, int size);
int BIO_write(BIO *b, const void *buf, int len);
int BIO_puts(BIO *b, const char *buf);
int BIO_read(BIO *b, void *buf, int len);
int BIO_gets(BIO *b, char *buf, int size);
int BIO_write(BIO *b, const void *buf, int len);
int BIO_puts(BIO *b, const char *buf);
=head1 DESCRIPTION
@@ -20,20 +22,22 @@ the data in B<buf>.
BIO_gets() performs the BIOs "gets" operation and places the data
in B<buf>. Usually this operation will attempt to read a line of data
from the BIO of maximum length B<len>. There are exceptions to this
however, for example BIO_gets() on a digest BIO will calculate and
from the BIO of maximum length B<len-1>. There are exceptions to this,
however; for example, BIO_gets() on a digest BIO will calculate and
return the digest and other BIOs may not support BIO_gets() at all.
The returned string is always NUL-terminated.
BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>.
BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
=head1 RETURN VALUES
All these functions return either the amount of data successfully read or
written (if the return value is positive) or that no data was successfully
read or written if the result is 0 or -1. If the return value is -2 then
the operation is not implemented in the specific BIO type.
the operation is not implemented in the specific BIO type. The trailing
NUL is not included in the length returned by BIO_gets().
=head1 NOTES
@@ -52,15 +56,24 @@ I/O structure and may block as a result. Instead select() (or equivalent)
should be combined with non blocking I/O so successive reads will request
a retry instead of blocking.
See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
See L<BIO_should_retry(3)> for details of how to
determine the cause of a retry and other I/O issues.
If the BIO_gets() function is not supported by a BIO then it possible to
work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
work around this by adding a buffering BIO L<BIO_f_buffer(3)>
to the chain.
=head1 SEE ALSO
L<BIO_should_retry(3)|BIO_should_retry(3)>
L<BIO_should_retry(3)>
TBA
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

119
doc/crypto/BIO_s_accept.pod
View File

@@ -1,18 +1,23 @@
=pod
=encoding utf8
=head1 NAME
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept,
BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
BIO_get_bind_mode, BIO_do_accept - accept BIO
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios,
BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD *BIO_s_accept(void);
const BIO_METHOD *BIO_s_accept(void);
long BIO_set_accept_port(BIO *b, char *name);
long BIO_set_accept_name(BIO *b, char *name);
char *BIO_get_accept_name(BIO *b);
long BIO_set_accept_port(BIO *b, char *port);
char *BIO_get_accept_port(BIO *b);
BIO *BIO_new_accept(char *host_port);
@@ -21,11 +26,7 @@ BIO_get_bind_mode, BIO_do_accept - accept BIO
long BIO_set_accept_bios(BIO *b, char *bio);
long BIO_set_bind_mode(BIO *b, long mode);
long BIO_get_bind_mode(BIO *b, long dummy);
#define BIO_BIND_NORMAL 0
#define BIO_BIND_REUSEADDR_IF_UNUSED 1
#define BIO_BIND_REUSEADDR 2
long BIO_get_bind_mode(BIO *b);
int BIO_do_accept(BIO *b);
@@ -49,23 +50,30 @@ If the close flag is set on an accept BIO then any active
connection on that chain is shutdown and the socket closed when
the BIO is freed.
Calling BIO_reset() on a accept BIO will close any active
Calling BIO_reset() on an accept BIO will close any active
connection and reset the BIO into a state where it awaits another
incoming connection.
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
the accept socket. See L<BIO_s_fd(3)>
BIO_set_accept_port() uses the string B<name> to set the accept
port. The port is represented as a string of the form "host:port",
BIO_set_accept_name() uses the string B<name> to set the accept
name. The name is represented as a string of the form "host:port",
where "host" is the interface to use and "port" is the port.
The host can be can be "*" which is interpreted as meaning
any interface; "port" has the same syntax
as the port specified in BIO_set_conn_port() for connect BIOs,
that is it can be a numerical port string or a string to lookup
using getservbyname() and a string table.
The host can be "*" or empty which is interpreted as meaning
any interface. If the host is an IPv6 address, it has to be
enclosed in brackets, for example "[::1]:https". "port" has the
same syntax as the port specified in BIO_set_conn_port() for
connect BIOs, that is it can be a numerical port string or a
string to lookup using getservbyname() and a string table.
BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into
BIO_set_accept_port() uses the string B<port> to set the accept
port. "port" has the same syntax as the port specified in
BIO_set_conn_port() for connect BIOs, that is it can be a numerical
port string or a string to lookup using getservbyname() and a string
table.
BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into
a single call: that is it creates a new accept BIO with port
B<host_port>.
@@ -74,19 +82,19 @@ BIO_set_nbio_accept() sets the accept socket to blocking mode
BIO_set_accept_bios() can be used to set a chain of BIOs which
will be duplicated and prepended to the chain when an incoming
connection is received. This is useful if, for example, a
connection is received. This is useful if, for example, a
buffering or SSL BIO is required for each connection. The
chain of BIOs must not be freed after this call, they will
be automatically freed when the accept BIO is freed.
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
the current bind mode. If BIO_BIND_NORMAL (the default) is set
the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set
then another socket cannot be bound to the same port. If
BIO_BIND_REUSEADDR is set then other sockets can bind to the
same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
attempt is first made to use BIO_BIN_NORMAL, if this fails
and the port is not in use then a second attempt is made
using BIO_BIND_REUSEADDR.
using B<BIO_BIND_REUSEADDR>.
BIO_do_accept() serves two functions. When it is first
called, after the accept BIO has been setup, it will attempt
@@ -137,13 +145,24 @@ then it is an indication that an accept attempt would block: the application
should take appropriate action to wait until the underlying socket has
accepted a connection and retry the call.
BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(),
BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and
BIO_do_accept() are macros.
BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(),
BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
=head1 RETURN VALUES
TBA
BIO_do_accept(),
BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
BIO_set_accept_bios(), and BIO_set_bind_mode(), return 1 for success and 0 or
-1 for failure.
BIO_get_accept_name() returns the accept name or NULL on error.
BIO_get_accept_port() returns the port as a string or NULL on error.
BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
BIO_new_accept() returns a BIO or NULL on error.
=head1 EXAMPLE
@@ -151,34 +170,36 @@ This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
BIO *abio, *cbio, *cbio2;
ERR_load_crypto_strings();
abio = BIO_new_accept("4444");
/* First call to BIO_accept() sets up accept BIO */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(0);
abio = BIO_new_accept("4444");
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Wait for incoming connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
fprintf(stderr, "Connection 1 established\n");
/* Retrieve BIO for connection */
cbio = BIO_pop(abio);
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
fprintf(stderr, "Sent out data on connection 1\n");
/* Wait for another connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
fprintf(stderr, "Connection 2 established\n");
/* Close accept BIO to refuse further connections */
cbio2 = BIO_pop(abio);
BIO_free(abio);
@@ -186,10 +207,18 @@ down each and finally closes both down.
fprintf(stderr, "Sent out data on connection 2\n");
BIO_puts(cbio, "Connection 1: Second connection established\n");
/* Close the two established connections */
BIO_free(cbio);
BIO_free(cbio2);
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

60
doc/crypto/BIO_s_bio.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
@@ -11,24 +13,22 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
#include <openssl/bio.h>
BIO_METHOD *BIO_s_bio(void);
const BIO_METHOD *BIO_s_bio(void);
#define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
#define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
int BIO_make_bio_pair(BIO *b1, BIO *b2);
int BIO_destroy_bio_pair(BIO *b);
int BIO_shutdown_wr(BIO *b);
#define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
#define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
#define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
int BIO_set_write_buf_size(BIO *b, long size);
size_t BIO_get_write_buf_size(BIO *b, long size);
int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
#define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
int BIO_get_write_guarantee(BIO *b);
size_t BIO_ctrl_get_write_guarantee(BIO *b);
#define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
int BIO_get_read_request(BIO *b);
size_t BIO_ctrl_get_read_request(BIO *b);
int BIO_ctrl_reset_read_request(BIO *b);
=head1 DESCRIPTION
@@ -65,7 +65,7 @@ up any half of the pair will automatically destroy the association.
BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
writes on BIO B<b> are allowed (they will return an error). Reads on the other
half of the pair will return any pending data or EOF when all pending data has
been read.
been read.
BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
If the size is not initialized a default value is used. This is currently
@@ -123,6 +123,11 @@ never sent!
BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
shutdown.
BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(),
BIO_set_write_buf_size(), BIO_get_write_buf_size(),
BIO_get_write_guarantee(), and BIO_get_read_request() are implemented
as macros.
=head1 RETURN VALUES
BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
@@ -139,9 +144,9 @@ without having to go through the SSL-interface.
BIO *internal_bio, *network_bio;
...
BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
SSL_set_bio(ssl, internal_bio, internal_bio);
SSL_operations();
SSL_operations(); //e.g SSL_read and SSL_write
...
application | TLS-engine
@@ -150,12 +155,16 @@ without having to go through the SSL-interface.
| /\ ||
| || \/
| BIO-pair (internal_bio)
+----------< BIO-pair (network_bio)
| BIO-pair (network_bio)
| || /\
| \/ ||
+-----------< BIO_operations()
| |
socket |
| |
socket
...
SSL_free(ssl); /* implicitly frees internal_bio */
SSL_free(ssl); /* implicitly frees internal_bio */
BIO_free(network_bio);
...
@@ -165,13 +174,13 @@ buffer is full or the read buffer is drained. Then the application has to
flush the write buffer and/or fill the read buffer.
Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
and must be transfered to the network. Use BIO_ctrl_get_read_request() to
and must be transferred to the network. Use BIO_ctrl_get_read_request() to
find out, how many bytes must be written into the buffer before the
SSL_operation() can successfully be continued.
=head1 WARNING
As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
condition, but there is still data in the write buffer. An application must
not rely on the error value of SSL_operation() but must assure that the
write buffer is always flushed first. Otherwise a deadlock may occur as
@@ -179,7 +188,16 @@ the peer might be waiting for the data before being able to continue.
=head1 SEE ALSO
L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)>
L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
L<BIO_should_retry(3)>, L<BIO_read(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

78
doc/crypto/BIO_s_connect.pod
View File

@@ -1,28 +1,29 @@
=pod
=encoding utf8
=head1 NAME
BIO_set_conn_address, BIO_get_conn_address,
BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
BIO_get_conn_hostname,
BIO_get_conn_port,
BIO_set_nbio, BIO_do_connect - connect BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_connect(void);
const BIO_METHOD * BIO_s_connect(void);
BIO *BIO_new_connect(char *name);
long BIO_set_conn_hostname(BIO *b, char *name);
long BIO_set_conn_port(BIO *b, char *port);
long BIO_set_conn_ip(BIO *b, char *ip);
long BIO_set_conn_int_port(BIO *b, char *port);
char *BIO_get_conn_hostname(BIO *b);
char *BIO_get_conn_port(BIO *b);
char *BIO_get_conn_ip(BIO *b);
long BIO_get_conn_int_port(BIO *b);
long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
const char *BIO_get_conn_hostname(BIO *b);
const char *BIO_get_conn_port(BIO *b);
const BIO_ADDR *BIO_get_conn_address(BIO *b);
long BIO_set_nbio(BIO *b, long n);
@@ -57,36 +58,33 @@ it also returns the socket . If B<c> is not NULL it should be of
type (int *).
BIO_set_conn_hostname() uses the string B<name> to set the hostname.
The hostname can be an IP address. The hostname can also include the
port in the form hostname:port . It is also acceptable to use the
form "hostname/any/other/path" or "hostname:port/any/other/path".
The hostname can be an IP address; if the address is an IPv6 one, it
must be enclosed with brackets. The hostname can also include the
port in the form hostname:port.
BIO_set_conn_port() sets the port to B<port>. B<port> can be the
numerical form or a string such as "http". A string will be looked
up first using getservbyname() on the host platform but if that
fails a standard table of port names will be used. Currently the
list is http, telnet, socks, https, ssl, ftp, gopher and wais.
fails a standard table of port names will be used. This internal
list is http, telnet, socks, https, ssl, ftp, and gopher.
BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
that is four bytes specifying the IP address in big-endian form.
BIO_set_conn_int_port() sets the port using B<port>. B<port> should
be of type (int *).
BIO_set_conn_address() sets the address and port information using
a BIO_ADDR(3ssl).
BIO_get_conn_hostname() returns the hostname of the connect BIO or
NULL if the BIO is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
BIO_get_conn_port() returns the port as a string.
This return value is an internal pointer which should not be modified.
BIO_get_conn_ip() returns the IP address in binary form.
BIO_get_conn_int_port() returns the port as an int.
BIO_get_conn_address() returns the address information as a BIO_ADDR.
This return value is an internal pointer which should not be modified.
BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
is set. Blocking I/O is the default. The call to BIO_set_nbio()
should be made before the connection is established because
should be made before the connection is established because
non blocking I/O is set during the connect process.
BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
@@ -169,19 +167,20 @@ to retrieve a page and copy the result to standard output.
BIO *cbio, *out;
int len;
char tmpbuf[1024];
ERR_load_crypto_strings();
cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
if (BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
exit(1);
}
BIO_puts(cbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(cbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
for ( ; ; ) {
len = BIO_read(cbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);
@@ -189,4 +188,15 @@ to retrieve a page and copy the result to standard output.
=head1 SEE ALSO
TBA
L<BIO_ADDR(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

53
doc/crypto/BIO_s_fd.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
@@ -8,10 +10,10 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
#include <openssl/bio.h>
BIO_METHOD * BIO_s_fd(void);
const BIO_METHOD *BIO_s_fd(void);
#define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
#define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
int BIO_set_fd(BIO *b, int fd, int c);
int BIO_get_fd(BIO *b, int *c);
BIO *BIO_new_fd(int fd, int close_flag);
@@ -23,46 +25,43 @@ round the platforms file descriptor routines such as read() and write().
BIO_read() and BIO_write() read or write the underlying descriptor.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then then close() is called on the underlying
If the close flag is set then close() is called on the underlying
file descriptor when the BIO is freed.
BIO_reset() attempts to change the file pointer to the start of file
using lseek(fd, 0, 0).
such as by using B<lseek(fd, 0, 0)>.
BIO_seek() sets the file pointer to position B<ofs> from start of file
using lseek(fd, ofs, 0).
such as by using B<lseek(fd, ofs, 0)>.
BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
BIO_tell() returns the current file position such as by calling
B<lseek(fd, 0, 1)>.
BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
flag to B<c>.
BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
returns the file descriptor. If B<c> is not NULL it should be of type
(int *).
returns the file descriptor.
BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
=head1 NOTES
The behaviour of BIO_read() and BIO_write() depends on the behavior of the
platforms read() and write() calls on the descriptor. If the underlying
platforms read() and write() calls on the descriptor. If the underlying
file descriptor is in a non blocking mode then the BIO will behave in the
manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)>
manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)>
manual pages.
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
BIO_set_fd() and BIO_get_fd() are implemented as macros.
=head1 RETURN VALUES
BIO_s_fd() returns the file descriptor BIO method.
BIO_reset() returns zero for success and -1 if an error occurred.
BIO_seek() and BIO_tell() return the current file position or -1
is an error occurred. These values reflect the underlying lseek()
behaviour.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the file descriptor or -1 if the BIO has not
@@ -76,14 +75,26 @@ occurred.
This is a file descriptor BIO version of "Hello World":
BIO *out;
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
L<BIO_seek(3)>, L<BIO_tell(3)>,
L<BIO_reset(3)>, L<BIO_read(3)>,
L<BIO_write(3)>, L<BIO_puts(3)>,
L<BIO_gets(3)>, L<BIO_printf(3)>,
L<BIO_set_close(3)>, L<BIO_get_close(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

43
doc/crypto/BIO_s_file.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
@@ -10,12 +12,12 @@ BIO_rw_filename - FILE bio
#include <openssl/bio.h>
BIO_METHOD * BIO_s_file(void);
const BIO_METHOD * BIO_s_file(void);
BIO *BIO_new_file(const char *filename, const char *mode);
BIO *BIO_new_fp(FILE *stream, int flags);
BIO_set_fp(BIO *b,FILE *fp, int flags);
BIO_get_fp(BIO *b,FILE **fpp);
BIO_set_fp(BIO *b, FILE *fp, int flags);
BIO_get_fp(BIO *b, FILE **fpp);
int BIO_read_filename(BIO *b, char *name)
int BIO_write_filename(BIO *b, char *name)
@@ -92,15 +94,15 @@ Alternative technique:
BIO *bio_out;
bio_out = BIO_new(BIO_s_file());
if(bio_out == NULL) /* Error ... */
if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
if (bio_out == NULL) /* Error ... */
if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
BIO_printf(bio_out, "Hello World\n");
Write to a file:
BIO *out;
out = BIO_new_file("filename.txt", "w");
if(!out) /* Error occurred */
if (!out) /* Error occurred */
BIO_printf(out, "Hello World\n");
BIO_free(out);
@@ -108,8 +110,8 @@ Alternative technique:
BIO *out;
out = BIO_new(BIO_s_file());
if(out == NULL) /* Error ... */
if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
if (out == NULL) /* Error ... */
if (!BIO_write_filename(out, "filename.txt")) /* Error ... */
BIO_printf(out, "Hello World\n");
BIO_free(out);
@@ -128,7 +130,7 @@ BIO_seek() returns the same value as the underlying fseek() function:
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() return 1 for success or 0 for failure.
=head1 BUGS
@@ -140,9 +142,20 @@ occurred this differs from other types of BIO which will typically return
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
L<BIO_seek(3)>, L<BIO_tell(3)>,
L<BIO_reset(3)>, L<BIO_flush(3)>,
L<BIO_read(3)>,
L<BIO_write(3)>, L<BIO_puts(3)>,
L<BIO_gets(3)>, L<BIO_printf(3)>,
L<BIO_set_close(3)>, L<BIO_get_close(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

47
doc/crypto/BIO_s_mem.pod
View File

@@ -1,7 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BIO_s_secmem,
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
@@ -9,23 +12,27 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
#include <openssl/bio.h>
BIO_METHOD * BIO_s_mem(void);
const BIO_METHOD * BIO_s_mem(void);
const BIO_METHOD * BIO_s_secmem(void);
BIO_set_mem_eof_return(BIO *b,int v)
BIO_set_mem_eof_return(BIO *b, int v)
long BIO_get_mem_data(BIO *b, char **pp)
BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c)
BIO_get_mem_ptr(BIO *b, BUF_MEM **pp)
BIO *BIO_new_mem_buf(const void *buf, int len);
=head1 DESCRIPTION
BIO_s_mem() return the memory BIO method function.
BIO_s_mem() return the memory BIO method function.
A memory BIO is a source/sink BIO which uses memory for its I/O. Data
written to a memory BIO is stored in a BUF_MEM structure which is extended
as appropriate to accommodate the stored data.
BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used
for buffer storage.
Any data written to a memory BIO can be recalled by reading from it.
Unless the memory BIO is read only any data read from it is deleted from
the BIO.
@@ -35,9 +42,10 @@ Memory BIOs support BIO_gets() and BIO_puts().
If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
BUF_MEM structure is also freed.
Calling BIO_reset() on a read write memory BIO clears any data in it. On a
read only BIO it restores the BIO to its original state and the read only
data can be read again.
Calling BIO_reset() on a read write memory BIO clears any data in it if the
flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag
BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and
the data can be read again.
BIO_eof() is true if no data is in the BIO.
@@ -79,22 +87,19 @@ read in small chunks the operation can be very slow. The use of a read only
memory BIO avoids this problem. If the BIO must be read write then adding
a buffering BIO to the chain will speed up the process.
Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
give undefined results, including perhaps a program crash.
=head1 BUGS
There should be an option to set the maximum size of a memory BIO.
There should be a way to "rewind" a read write BIO without destroying
its contents.
The copying operation should not occur after every small read of a large BIO
to improve efficiency.
=head1 EXAMPLE
Create a memory BIO and write some data to it:
BIO *mem = BIO_new(BIO_s_mem());
BIO_puts(mem, "Hello World\n");
BIO_puts(mem, "Hello World\n");
Create a read only memory BIO:
@@ -108,8 +113,14 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
BIO_get_mem_ptr(mem, &bptr);
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BIO_s_null.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BIO_s_null - null data sink
@@ -8,7 +10,7 @@ BIO_s_null - null data sink
#include <openssl/bio.h>
BIO_METHOD * BIO_s_null(void);
const BIO_METHOD * BIO_s_null(void);
=head1 DESCRIPTION
@@ -32,6 +34,13 @@ by adding a null sink BIO to the end of the chain
BIO_s_null() returns the null sink BIO method.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

31
doc/crypto/BIO_s_socket.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BIO_s_socket, BIO_new_socket - socket BIO
@@ -8,10 +10,7 @@ BIO_s_socket, BIO_new_socket - socket BIO
#include <openssl/bio.h>
BIO_METHOD *BIO_s_socket(void);
long BIO_set_fd(BIO *b, int fd, long close_flag);
long BIO_get_fd(BIO *b, int *c);
const BIO_METHOD *BIO_s_socket(void);
BIO *BIO_new_socket(int sock, int close_flag);
@@ -26,12 +25,6 @@ BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then the socket is shut down and closed
when the BIO is freed.
BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close
flag to B<close_flag>.
BIO_get_fd() places the socket in B<c> if it is not NULL, it also
returns the socket. If B<c> is not NULL it should be of type (int *).
BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
=head1 NOTES
@@ -44,20 +37,20 @@ platforms sockets are not file descriptors and use distinct I/O routines,
Windows is one such platform. Any code mixing the two will not work on
all platforms.
BIO_set_fd() and BIO_get_fd() are macros.
=head1 RETURN VALUES
BIO_s_socket() returns the socket BIO method.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the socket or -1 if the BIO has not been
initialized.
BIO_new_socket() returns the newly allocated BIO or NULL is an error
occurred.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

193
doc/crypto/BIO_set_callback.pod
View File

@@ -1,100 +1,208 @@
=pod
=encoding utf8
=head1 NAME
BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
BIO_debug_callback - BIO callback functions
BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback,
BIO_callback_fn_ex, BIO_callback_fn
- BIO callback functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_set_callback(b,cb) ((b)->callback=(cb))
#define BIO_get_callback(b) ((b)->callback)
#define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
#define BIO_get_callback_arg(b) ((b)->cb_arg)
typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
size_t len, int argi,
long argl, int ret, size_t *processed);
typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
long argl, long ret);
long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
long argl,long ret);
void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
typedef long (*callback)(BIO *b, int oper, const char *argp,
int argi, long argl, long retvalue);
void BIO_set_callback(BIO *b, BIO_callack_fn cb);
BIO_callack_fn BIO_get_callback(BIO *b);
void BIO_set_callback_arg(BIO *b, char *arg);
char *BIO_get_callback_arg(const BIO *b);
long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
long argl, long ret);
=head1 DESCRIPTION
BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
they are both macros. The callback is called during most high level BIO
operations. It can be used for debugging purposes to trace operations on
a BIO or to modify its operation.
BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
callback. The callback is called during most high level BIO operations. It can
be used for debugging purposes to trace operations on a BIO or to modify its
operation.
BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO
callback. New code should not use these functions, but they are retained for
backwards compatbility. Any callback set via BIO_set_callback_ex() will get
called in preference to any set by BIO_set_callback().
BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
used to set and retrieve an argument for use in the callback.
BIO_debug_callback() is a standard debugging callback which prints
out information relating to each BIO operation. If the callback
argument is set if is interpreted as a BIO to send the information
argument is set it is interpreted as a BIO to send the information
to, otherwise stderr is used.
callback() is the callback function itself. The meaning of each
argument is described below.
BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
is the type of the old format callback function. The meaning of each argument
is described below:
=over
=item B<b>
The BIO the callback is attached to is passed in B<b>.
=item B<oper>
B<oper> is set to the operation being performed. For some operations
the callback is called twice, once before and once after the actual
operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
=item B<len>
The length of the data requested to be read or written. This is only useful if
B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
=item B<argp> B<argi> B<argl>
The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
the value of B<oper>, that is the operation being performed.
B<retvalue> is the return value that would be returned to the
=item B<processed>
B<processed> is a pointer to a location which will be updated with the amount of
data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE,
BIO_CB_GETS and BIO_CB_PUTS.
=item B<ret>
B<ret> is the return value that would be returned to the
application if no callback were present. The actual value returned
is the return value of the callback itself. In the case of callbacks
called before the actual BIO operation 1 is placed in retvalue, if
called before the actual BIO operation 1 is placed in B<ret>, if
the return value is not positive it will be immediately returned to
the application and the BIO operation will not be performed.
The callback should normally simply return B<retvalue> when it has
finished processing, unless if specifically wishes to modify the
=back
The callback should normally simply return B<ret> when it has
finished processing, unless it specifically wishes to modify the
value returned to the application.
=head1 CALLBACK OPERATIONS
In the notes below, B<callback> defers to the actual callback
function that is called.
=over 4
=item B<BIO_free(b)>
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
free operation.
callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
=item B<BIO_read(b, out, outl)>
or
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
is called before the free operation.
=item B<BIO_read_ex(b, data, dlen, readbytes)>
callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, readbytes)
or
callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
is called before the read and
callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, readbytes)
or
callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_write(b, in, inl)>
=item B<BIO_write(b, data, dlen, written)>
callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, written)
or
callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
is called before the write and
callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, written)
or
callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
after.
=item B<BIO_gets(b, out, outl)>
=item B<BIO_gets(b, buf, size)>
callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
or
callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue, readbytes)
or
callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_puts(b, in)>
=item B<BIO_puts(b, buf)>
callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
or
callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, written)
or
callback(b, BIO_CB_WRITE|BIO_CB_RETURN, buf, 0, 0L, retvalue)
callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
after.
=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
or
callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
is called before the call and
callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
or
callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
after.
=back
@@ -103,6 +211,13 @@ callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

56
doc/crypto/BIO_should_retry.pod
View File

@@ -1,29 +1,27 @@
=pod
=encoding utf8
=head1 NAME
BIO_should_retry, BIO_should_read, BIO_should_write,
BIO_should_read, BIO_should_write,
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
#define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
#define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
#define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
#define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
int BIO_should_read(BIO *b);
int BIO_should_write(BIO *b);
int BIO_should_io_special(iBIO *b);
int BIO_retry_type(BIO *b);
int BIO_should_retry(BIO *b);
#define BIO_FLAGS_READ 0x01
#define BIO_FLAGS_WRITE 0x02
#define BIO_FLAGS_IO_SPECIAL 0x04
#define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08
BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
void BIO_set_retry_reason(BIO *bio, int reason);
=head1 DESCRIPTION
@@ -51,7 +49,7 @@ B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
these.
BIO_get_retry_BIO() determines the precise reason for the special
condition, it returns the BIO that caused this condition and if
condition, it returns the BIO that caused this condition and if
B<reason> is not NULL it contains the reason code. The meaning of
the reason code and the action that should be taken depends on
the type of BIO that resulted in this condition.
@@ -59,8 +57,14 @@ the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if
passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
BIO_set_retry_reason() sets the retry reason for a special condition for a given
BIO. This would usually only be called by BIO implementations.
=head1 NOTES
BIO_should_read(), BIO_should_write(), BIO_should_io_special(),
BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
If BIO_should_retry() returns false then the precise "error condition"
depends on the BIO type that caused it and the return code of the BIO
operation. For example if a call to BIO_read() on a socket BIO returns
@@ -94,7 +98,7 @@ available and then retry the BIO operation. By combining the retry
conditions of several non blocking BIOs in a single select() call
it is possible to service several BIOs in a single thread, though
the performance may be poor if SSL BIOs are present because long delays
can occur during the initial handshake process.
can occur during the initial handshake process.
It is possible for a BIO to block indefinitely if the underlying I/O
structure cannot process or return any data. This depends on the behaviour of
@@ -111,4 +115,20 @@ the entire structure can be read or written.
=head1 SEE ALSO
TBA
L<bio>
=head1 HISTORY
The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

81
doc/crypto/BN_BLINDING_new.pod
View File

@@ -1,39 +1,40 @@
=pod
=encoding utf8
=head1 NAME
BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM
functions.
BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread,
BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
BIGNUM *mod);
BIGNUM *mod);
void BN_BLINDING_free(BN_BLINDING *b);
int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
BN_CTX *ctx);
int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
#ifndef OPENSSL_NO_DEPRECATED
unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
#endif
CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *);
BN_CTX *ctx);
int BN_BLINDING_is_current_thread(BN_BLINDING *b);
void BN_BLINDING_set_current_thread(BN_BLINDING *b);
int BN_BLINDING_lock(BN_BLINDING *b);
int BN_BLINDING_unlock(BN_BLINDING *b);
unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
BN_MONT_CTX *m_ctx);
const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
BN_MONT_CTX *m_ctx);
=head1 DESCRIPTION
@@ -41,6 +42,7 @@ BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
BN_BLINDING_free() frees the B<BN_BLINDING> structure.
If B<b> is NULL, nothing is done.
BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
the B<A> and B<Ai> or, after specific number of uses and if the
@@ -57,11 +59,16 @@ BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
with B<r> set to NULL.
BN_BLINDING_thread_id() provides access to the B<CRYPTO_THREADID>
object within the B<BN_BLINDING> structure. This is to help users
provide proper locking if needed for multi-threaded use. The "thread
id" object of a newly allocated B<BN_BLINDING> structure is
initialised to the thread id in which BN_BLINDING_new() was called.
BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING>
structure is owned by the current thread. This is to help users
provide proper locking if needed for multi-threaded use.
BN_BLINDING_set_current_thread() sets the current thread as the
owner of the B<BN_BLINDING> structure.
BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
@@ -86,30 +93,36 @@ BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
success and 0 if an error occurred.
BN_BLINDING_thread_id() returns a pointer to the thread id object
within a B<BN_BLINDING> object.
BN_BLINDING_is_current_thread() returns 1 if the current thread owns
the B<BN_BLINDING> object, 0 otherwise.
BN_BLINDING_set_current_thread() doesn't return anything.
BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
succeeded or 0 on error.
BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
(a B<unsigned long> value).
BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
parameters or NULL on error.
=head1 SEE ALSO
L<bn(3)|bn(3)>
L<bn(3)>
=head1 HISTORY
BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it
deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id.
BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it
deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().
BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8
=head1 COPYRIGHT
=head1 AUTHOR
Copyright 2005-2016 The OpenSSL Project Authors. All Rights Reserved.
Nils Larsch for the OpenSSL project (http://www.openssl.org).
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

63
doc/crypto/BN_CTX_new.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
=head1 SYNOPSIS
@@ -10,13 +12,10 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX *BN_CTX_new(void);
BN_CTX *BN_CTX_secure_new(void);
void BN_CTX_free(BN_CTX *c);
Deprecated:
void BN_CTX_init(BN_CTX *c);
=head1 DESCRIPTION
A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
@@ -24,34 +23,56 @@ library functions. Since dynamic memory allocation to create B<BIGNUM>s
is rather expensive when used in conjunction with repeated subroutine
calls, the B<BN_CTX> structure is used.
BN_CTX_new() allocates and initializes a B<BN_CTX>
structure.
BN_CTX_new() allocates and initializes a B<BN_CTX> structure.
BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure
but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the
B<BIGNUM>s.
BN_CTX_free() frees the components of the B<BN_CTX>, and if it was
created by BN_CTX_new(), also the structure itself.
If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>,
L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX>
If L<BN_CTX_start(3)> has been used on the B<BN_CTX>,
L<BN_CTX_end(3)> must be called before the B<BN_CTX>
may be freed by BN_CTX_free().
BN_CTX_init() (deprecated) initializes an existing uninitialized B<BN_CTX>.
This should not be used for new programs. Use BN_CTX_new() instead.
If B<c> is NULL, nothing is done.
=head1 RETURN VALUES
BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails,
it returns B<NULL> and sets an error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>.
If the allocation fails,
they return B<NULL> and sets an error code that can be obtained by
L<ERR_get_error(3)>.
BN_CTX_init() and BN_CTX_free() have no return values.
BN_CTX_free() has no return values.
=head1 REMOVED FUNCTIONALITY
void BN_CTX_init(BN_CTX *c);
BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should
replace use of BN_CTX_init with BN_CTX_new instead:
BN_CTX *ctx;
ctx = BN_CTX_new();
if(!ctx) /* Handle error */
...
BN_CTX_free(ctx);
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
L<BN_CTX_start(3)|BN_CTX_start(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
L<BN_CTX_start(3)>
=head1 HISTORY
BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay
and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b.
BN_CTX_init() was removed in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/crypto/BN_CTX_start.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
@@ -17,7 +19,7 @@ BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
=head1 DESCRIPTION
These functions are used to obtain temporary B<BIGNUM> variables from
a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)|BN_CTX_new(3)>)
a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)>)
in order to save the overhead of repeatedly creating and
freeing B<BIGNUM>s in functions that are called from inside a loop.
@@ -38,15 +40,20 @@ BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error.
Once BN_CTX_get() has failed, the subsequent calls will return B<NULL>
as well, so it is sufficient to check the return value of the last
BN_CTX_get() call. In case of an error, an error code is set, which
can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<BN_CTX_new(3)|BN_CTX_new(3)>
L<BN_CTX_new(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

31
doc/crypto/BN_add.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_add, BN_sub, BN_mul, BN_sqr, BN_div, BN_mod, BN_nnmod, BN_mod_add,
@@ -49,10 +51,11 @@ BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
For multiplication by powers of 2, use L<BN_lshift(3)|BN_lshift(3)>.
For multiplication by powers of 2, use L<BN_lshift(3)>.
BN_sqr() takes the square of I<a> and places the result in I<r>
(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
@@ -80,8 +83,8 @@ BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
repeated computations using the same modulus, see
L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> and
L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>.
L<BN_mod_mul_montgomery(3)> and
L<BN_mod_mul_reciprocal(3)>.
BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
result in I<r>.
@@ -98,7 +101,7 @@ places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
I<b>.
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
temporary variables; see L<BN_CTX_new(3)|BN_CTX_new(3)>.
temporary variables; see L<BN_CTX_new(3)>.
Unless noted otherwise, the result B<BIGNUM> must be different from
the arguments.
@@ -107,20 +110,20 @@ the arguments.
For all functions, 1 is returned for success, 0 on error. The return
value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<BN_CTX_new(3)>,
L<BN_add_word(3)>, L<BN_set_bit(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(),
BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and
OpenSSL. The I<ctx> argument to BN_mul() was added in SSLeay
0.9.1b. BN_exp() appeared in SSLeay 0.9.0.
BN_nnmod(), BN_mod_add(), BN_mod_sub(), and BN_mod_sqr() were added in
OpenSSL 0.9.7.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/crypto/BN_add_word.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_add_word, BN_sub_word, BN_mul_word, BN_div_word, BN_mod_word - arithmetic
@@ -40,22 +42,22 @@ For BN_div_word() and BN_mod_word(), B<w> must not be 0.
=head1 RETURN VALUES
BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0
on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
on error. The error codes can be obtained by L<ERR_get_error(3)>.
BN_mod_word() and BN_div_word() return B<a>%B<w> on success and
B<(BN_ULONG)-1> if an error occurred.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_add_word() and BN_mod_word() are available in all versions of
SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and
BN_sub_word() and BN_mul_word() in SSLeay 0.9.0.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Before 0.9.8a the return value for BN_div_word() and BN_mod_word()
in case of an error was 0.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

56
doc/crypto/BN_bn2bin.pod
View File

@@ -1,17 +1,25 @@
=pod
=encoding utf8
=head1 NAME
BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn,
BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions
BN_bn2binpad,
BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec,
BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi,
BN_mpi2bn - format conversions
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_bn2bin(const BIGNUM *a, unsigned char *to);
int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
char *BN_bn2hex(const BIGNUM *a);
char *BN_bn2dec(const BIGNUM *a);
int BN_hex2bn(BIGNUM **a, const char *str);
@@ -29,20 +37,28 @@ BN_bn2bin() converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
memory.
BN_bn2binpad() also converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<tolen> indicates the length of the output buffer
B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than
BN_num_bytes(B<a>) an error is returned.
BN_bin2bn() converts the positive integer in big-endian form of length
B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
NULL, a new B<BIGNUM> is created.
BN_bn2lebinpad() and BN_bin2lbn() are identical to BN_bn2binpad() and
BN_bin2bn() except the buffer is in little-endian format.
BN_bn2hex() and BN_bn2dec() return printable strings containing the
hexadecimal and decimal encoding of B<a> respectively. For negative
numbers, the string is prefaced with a leading '-'. The string must be
freed later using OPENSSL_free().
BN_hex2bn() converts the string B<str> containing a hexadecimal number
to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new
B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's
length in hexadecimal digits. If the string starts with '-', the
number is negative.
BN_hex2bn() takes as many characters as possible from the string B<str>,
including the leading character '-' which means negative, to form a valid
hexadecimal number representation and converts them to a B<BIGNUM> and
stores it in **B<bn>. If *B<bn> is NULL, a new B<BIGNUM> is created. If
B<bn> is NULL, it only computes the length of valid representation.
A "negative zero" is converted to zero.
BN_dec2bn() is the same using the decimal system.
@@ -69,9 +85,12 @@ if B<ret> is NULL.
BN_bn2bin() returns the length of the big-endian number placed at B<to>.
BN_bin2bn() returns the B<BIGNUM>, NULL on error.
BN_bn2binpad() returns the number of bytes written or -1 if the supplied
buffer is too small.
BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL
on error. BN_hex2bn() and BN_dec2bn() return the number of characters
used in parsing, or 0 on error, in which
on error. BN_hex2bn() and BN_dec2bn() return the the length of valid
representation in hexadecimal or decimal digits, and 0 on error, in which
case no new B<BIGNUM> will be created.
BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
@@ -79,20 +98,21 @@ BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
BN_bn2mpi() returns the length of the representation. BN_mpi2bn()
returns the B<BIGNUM>, and NULL on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_zero(3)|BN_zero(3)>,
L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>,
L<BN_num_bytes(3)|BN_num_bytes(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<BN_zero(3)>,
L<ASN1_INTEGER_to_BN(3)>,
L<BN_num_bytes(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available
in all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and
BN_mpi2bn() were added in SSLeay 0.9.0.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BN_cmp.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_cmp, BN_ucmp, BN_is_zero, BN_is_one, BN_is_word, BN_is_odd - BIGNUM comparison and test functions
@@ -37,12 +39,15 @@ the condition is true, 0 otherwise.
=head1 SEE ALSO
L<bn(3)|bn(3)>
L<bn(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are
available in all versions of SSLeay and OpenSSL.
BN_is_odd() was added in SSLeay 0.8.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

47
doc/crypto/BN_copy.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BN_copy, BN_dup - copy BIGNUMs
BN_copy, BN_dup, BN_with_flags - copy BIGNUMs
=head1 SYNOPSIS
@@ -12,23 +14,58 @@ BN_copy, BN_dup - copy BIGNUMs
BIGNUM *BN_dup(const BIGNUM *from);
void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags);
=head1 DESCRIPTION
BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM>
containing the value B<from>.
BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places
significant restrictions on the copied data. Applications that do no adhere to
these restrictions may encounter unexpected side effects or crashes. For that
reason use of this function is discouraged. Any flags provided in B<flags> will
be set in B<dest> in addition to any flags already set in B<b>. For example this
might commonly be used to create a temporary copy of a BIGNUM with the
B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in
B<dest> will share some internal state with B<b>. For this reason the following
restrictions apply to the use of B<dest>:
=over 4
=item *
B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It
should not have been used for other purposes or initialised in any way.
=item *
B<dest> must only be used in "read-only" operations, i.e. typically those
functions where the relevant parameter is declared "const".
=item *
B<dest> must be used and freed before any further subsequent use of B<b>
=back
=head1 RETURN VALUES
BN_copy() returns B<to> on success, NULL on error. BN_dup() returns
the new B<BIGNUM>, and NULL on error. The error codes can be obtained
by L<ERR_get_error(3)|ERR_get_error(3)>.
by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
L<bn(3)>, L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

80
doc/crypto/BN_generate_prime.pod
View File

@@ -1,46 +1,58 @@
=pod
=encoding utf8
=head1 NAME
BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
BN_GENCB_set_old, BN_GENCB_set, BN_generate_prime, BN_is_prime,
BN_is_prime_fasttest - generate primes and test for primality
BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg,
BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test
for primality
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_generate_prime_ex(BIGNUM *ret,int bits,int safe, const BIGNUM *add,
int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add,
const BIGNUM *rem, BN_GENCB *cb);
int BN_is_prime_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, BN_GENCB *cb);
int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb);
int BN_is_prime_fasttest_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx,
int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx,
int do_trial_division, BN_GENCB *cb);
int BN_GENCB_call(BN_GENCB *cb, int a, int b);
#define BN_GENCB_set_old(gencb, callback, cb_arg) ...
BN_GENCB *BN_GENCB_new(void);
#define BN_GENCB_set(gencb, callback, cb_arg) ...
void BN_GENCB_free(BN_GENCB *cb);
void BN_GENCB_set_old(BN_GENCB *gencb,
void (*callback)(int, int, void *), void *cb_arg);
void BN_GENCB_set(BN_GENCB *gencb,
int (*callback)(int, int, BN_GENCB *), void *cb_arg);
void *BN_GENCB_get_arg(BN_GENCB *cb);
Deprecated:
#if OPENSSL_API_COMPAT < 0x00908000L
BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,
int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int,
void *), BN_CTX *ctx, void *cb_arg);
int BN_is_prime_fasttest(const BIGNUM *a, int checks,
void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg,
int do_trial_division);
#endif
=head1 DESCRIPTION
BN_generate_prime_ex() generates a pseudo-random prime number of
bit length B<bits>.
at least bit length B<bits>.
If B<ret> is not B<NULL>, it will be used to store the number.
If B<cb> is not B<NULL>, it is used as follows:
@@ -103,17 +115,23 @@ B<BN_GENCB> structure that are supported: "new" style and "old" style. New
programs should prefer the "new" style, whilst the "old" style is provided
for backwards compatibility purposes.
A BN_GENCB structure should be created through a call to BN_GENCB_new(),
and freed through a call to BN_GENCB_free().
For "new" style callbacks a BN_GENCB structure should be initialised with a
call to BN_GENCB_set, where B<gencb> is a B<BN_GENCB *>, B<callback> is of
call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of
type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>.
"Old" style callbacks are the same except they are initialised with a call
to BN_GENCB_set_old and B<callback> is of type
to BN_GENCB_set_old() and B<callback> is of type
B<void (*callback)(int, int, void *)>.
A callback is invoked through a call to B<BN_GENCB_call>. This will check
the type of the callback and will invoke B<callback(a, b, gencb)> for new
style callbacks or B<callback(a, b, cb_arg)> for old style.
It is possible to obtained the argument associated with a BN_GENCB structure
(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg.
BN_generate_prime (deprecated) works in the same way as
BN_generate_prime_ex but expects an old style callback function
directly in the B<callback> parameter, and an argument to pass to it in
@@ -132,19 +150,47 @@ prime with an error probability of less than 0.25^B<nchecks>, and
BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL>
otherwise.
BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB
structure.
Callback functions should return 1 on success or 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 REMOVED FUNCTIONALITY
As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure
directly, as in:
BN_GENCB callback;
Instead applications should create a BN_GENCB structure using BN_GENCB_new:
BN_GENCB *callback;
callback = BN_GENCB_new();
if(!callback) /* handle error */
...
BN_GENCB_free(callback);
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>
=head1 HISTORY
The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime()
were added in SSLeay 0.9.0. The B<ret> argument to BN_generate_prime()
was added in SSLeay 0.9.1.
BN_is_prime_fasttest() was added in OpenSSL 0.9.5.
BN_GENCB_new(), BN_GENCB_free(),
and BN_GENCB_get_arg() were added in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BN_mod_inverse.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_mod_inverse - compute inverse modulo n
@@ -23,14 +25,19 @@ variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>.
=head1 RETURN VALUES
BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and
NULL on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
NULL on error. The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_mod_inverse() is available in all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/crypto/BN_mod_mul_montgomery.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init,
BN_mod_mul_montgomery, BN_MONT_CTX_new,
BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
@@ -11,7 +13,6 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
#include <openssl/bn.h>
BN_MONT_CTX *BN_MONT_CTX_new(void);
void BN_MONT_CTX_init(BN_MONT_CTX *ctx);
void BN_MONT_CTX_free(BN_MONT_CTX *mont);
int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx);
@@ -29,12 +30,11 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
=head1 DESCRIPTION
These functions implement Montgomery multiplication. They are used
automatically when L<BN_mod_exp(3)|BN_mod_exp(3)> is called with suitable input,
automatically when L<BN_mod_exp(3)> is called with suitable input,
but they may be useful when several operations are to be performed
using the same modulus.
BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure.
BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>.
BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m>
by precomputing its inverse and a value R.
@@ -43,6 +43,7 @@ BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>.
BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if
it was created by BN_MONT_CTX_new(), also the structure itself.
If B<mont> is NULL, nothing is done.
BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places
the result in I<r>.
@@ -55,30 +56,15 @@ Note that I<a> must be non-negative and smaller than the modulus.
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
temporary variables.
The B<BN_MONT_CTX> structure is defined as follows:
typedef struct bn_mont_ctx_st
{
int ri; /* number of bits in R */
BIGNUM RR; /* R^2 (used to convert to Montgomery form) */
BIGNUM N; /* The modulus */
BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1
* (Ni is only stored for bignum algorithm) */
BN_ULONG n0; /* least significant word of Ni */
int flags;
} BN_MONT_CTX;
BN_to_montgomery() is a macro.
=head1 RETURN VALUES
BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL
on error.
BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values.
BN_MONT_CTX_free() has no return value.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 WARNING
@@ -87,15 +73,20 @@ outside the expected range.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
L<BN_CTX_new(3)|BN_CTX_new(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
L<BN_CTX_new(3)>
=head1 HISTORY
BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(),
BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery()
are available in all versions of SSLeay and OpenSSL.
BN_MONT_CTX_init() was removed in OpenSSL 1.1.0
BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

43
doc/crypto/BN_mod_mul_reciprocal.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new,
BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
reciprocal
@@ -11,7 +13,6 @@ reciprocal
#include <openssl/bn.h>
BN_RECP_CTX *BN_RECP_CTX_new(void);
void BN_RECP_CTX_init(BN_RECP_CTX *recp);
void BN_RECP_CTX_free(BN_RECP_CTX *recp);
int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx);
@@ -25,16 +26,16 @@ reciprocal
=head1 DESCRIPTION
BN_mod_mul_reciprocal() can be used to perform an efficient
L<BN_mod_mul(3)|BN_mod_mul(3)> operation when the operation will be performed
L<BN_mod_mul(3)> operation when the operation will be performed
repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m>
using B<recp>=1/B<m>, which is set as described below. B<ctx> is a
previously allocated B<BN_CTX> used for temporary variables.
BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure.
BN_RECP_CTX_init() initializes an existing uninitialized B<BN_RECP>.
BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it
was created by BN_RECP_CTX_new(), also the structure itself.
If B<recp> is NULL, nothing is done.
BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing
1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an
@@ -44,38 +45,34 @@ later be stored in B<recp>.
BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient
in B<dv> and the remainder in B<rem>.
The B<BN_RECP_CTX> structure is defined as follows:
typedef struct bn_recp_ctx_st
{
BIGNUM N; /* the divisor */
BIGNUM Nr; /* the reciprocal */
int num_bits;
int shift;
int flags;
} BN_RECP_CTX;
It cannot be shared between threads.
The B<BN_RECP_CTX> structure cannot be shared between threads.
=head1 RETURN VALUES
BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL
on error.
BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values.
BN_RECP_CTX_free() has no return value.
For the other functions, 1 is returned for success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
L<BN_CTX_new(3)|BN_CTX_new(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
L<BN_CTX_new(3)>
=head1 HISTORY
B<BN_RECP_CTX> was added in SSLeay 0.9.0. Before that, the function
BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal()
arguments were different.
BN_RECP_CTX_init() was removed in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

37
doc/crypto/BN_new.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
=head1 SYNOPSIS
@@ -10,7 +12,7 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
BIGNUM *BN_new(void);
void BN_init(BIGNUM *);
BIGNUM *BN_secure_new(void);
void BN_clear(BIGNUM *a);
@@ -20,8 +22,9 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
=head1 DESCRIPTION
BN_new() allocates and initializes a B<BIGNUM> structure. BN_init()
initializes an existing uninitialized B<BIGNUM>.
BN_new() allocates and initializes a B<BIGNUM> structure.
BN_secure_new() does the same except that the secure heap
OPENSSL_secure_malloc(3) is used to store the value.
BN_clear() is used to destroy sensitive data such as keys when they
are no longer needed. It erases the memory used by B<a> and sets it
@@ -30,24 +33,32 @@ to the value 0.
BN_free() frees the components of the B<BIGNUM>, and if it was created
by BN_new(), also the structure itself. BN_clear_free() additionally
overwrites the data before the memory is returned to the system.
If B<a> is NULL, nothing is done.
=head1 RETURN VALUES
BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails,
it returns B<NULL> and sets an error code that can be obtained
by L<ERR_get_error(3)|ERR_get_error(3)>.
BN_new() and BN_secure_new()
return a pointer to the B<BIGNUM>. If the allocation fails,
they return B<NULL> and set an error code that can be obtained
by L<ERR_get_error(3)>.
BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return
values.
BN_clear(), BN_free() and BN_clear_free() have no return values.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>
L<bn(3)>, L<ERR_get_error(3)>
=head1 HISTORY
BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in
all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay
0.9.1b.
BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/BN_num_bytes.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_num_bits, BN_num_bytes, BN_num_bits_word - get BIGNUM size
@@ -46,12 +48,16 @@ more probability).
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<DH_size(3)|DH_size(3)>, L<DSA_size(3)|DSA_size(3)>,
L<RSA_size(3)|RSA_size(3)>
L<bn(3)>, L<DH_size(3)>, L<DSA_size(3)>,
L<RSA_size(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in
all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/crypto/BN_rand.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number
@@ -23,13 +25,16 @@ B<bits> in length and stores it in B<rnd>.
If B<bits> is less than zero, or too small to
accomodate the requirements specified by the B<top> and B<bottom>
parameters, an error is returned.
If B<top> is -1, the
most significant bit of the random number can be zero. If B<top> is 0,
it is set to 1, and if B<top> is 1, the two most significant bits of
The B<top> parameters specifies
requirements on the most significant bit of the generated number.
If it is B<BN_RAND_TOP_ANY>, there is no constraint.
If it is B<BN_RAND_TOP_ONE>, the top bit must be one.
If it is B<BN_RAND_TOP_TWO>, the two most significant bits of
the number will be set to 1, so that the product of two such random
numbers will always have 2*B<bits> length. If B<bottom> is true, the
number will be odd. The value of B<bits> must be zero or greater. If B<bits> is
1 then B<top> cannot also be 1.
numbers will always have 2*B<bits> length.
If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it
is B<BN_RAND_BOTTOM_ANY> it can be odd or even.
If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>.
BN_pseudo_rand() does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for
@@ -46,18 +51,20 @@ The PRNG must be seeded prior to calling BN_rand() or BN_rand_range().
=head1 RETURN VALUES
The functions return 1 on success, 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)>
L<bn(3)>, L<ERR_get_error(3)>, L<rand(3)>,
L<RAND_add(3)>, L<RAND_bytes(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_rand() is available in all versions of SSLeay and OpenSSL.
BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case
and the function BN_rand_range() were added in OpenSSL 0.9.6a.
BN_pseudo_rand_range() was added in OpenSSL 0.9.6c.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

17
doc/crypto/BN_set_bit.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_set_bit, BN_clear_bit, BN_is_bit_set, BN_mask_bits, BN_lshift,
@@ -51,16 +53,19 @@ For the shift functions, B<r> and B<a> may be the same variable.
BN_is_bit_set() returns 1 if the bit is set, 0 otherwise.
All other functions return 1 for success, 0 on error. The error codes
can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, L<BN_add(3)|BN_add(3)>
L<bn(3)>, L<BN_num_bytes(3)>, L<BN_add(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(),
BN_lshift(), BN_lshift1(), BN_rshift(), and BN_rshift1() are available
in all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BN_swap.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_swap - exchange BIGNUMs
@@ -14,10 +16,15 @@ BN_swap - exchange BIGNUMs
BN_swap() exchanges the values of I<a> and I<b>.
L<bn(3)|bn(3)>
L<bn(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_swap was added in OpenSSL 0.9.7.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

28
doc/crypto/BN_zero.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
BN_zero, BN_one, BN_value_one, BN_set_word, BN_get_word - BIGNUM assignment
@@ -9,7 +11,7 @@ operations
#include <openssl/bn.h>
int BN_zero(BIGNUM *a);
void BN_zero(BIGNUM *a);
int BN_one(BIGNUM *a);
const BIGNUM *BN_value_one(void);
@@ -17,6 +19,12 @@ operations
int BN_set_word(BIGNUM *a, unsigned long w);
unsigned long BN_get_word(BIGNUM *a);
Deprecated:
#if OPENSSL_API_COMPAT < 0x00908000L
int BN_zero(BIGNUM *a);
#endif
=head1 DESCRIPTION
BN_zero(), BN_one() and BN_set_word() set B<a> to the values 0, 1 and
@@ -33,8 +41,10 @@ long.
BN_get_word() returns the value B<a>, and 0xffffffffL if B<a> cannot
be represented as an unsigned long.
BN_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise.
BN_one(), BN_set_word() and the deprecated version of BN_zero()
return 1 on success, 0 otherwise.
BN_value_one() returns the constant.
The preferred version of BN_zero() never fails and returns no value.
=head1 BUGS
@@ -45,15 +55,15 @@ unsigned long but this value is also returned on error.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)>
L<bn(3)>, L<BN_bn2bin(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_zero(), BN_one() and BN_set_word() are available in all versions of
SSLeay and OpenSSL. BN_value_one() and BN_get_word() were added in
SSLeay 0.8.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
BN_value_one() was changed to return a true const BIGNUM * in OpenSSL
0.9.7.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

22
doc/crypto/CMS_add0_cert.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
@@ -20,7 +22,7 @@ CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_ge
=head1 DESCRIPTION
CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>.
must be of type signed data or enveloped data.
must be of type signed data or enveloped data.
CMS_get1_certs() returns all certificates in B<cms>.
@@ -46,7 +48,7 @@ than once.
=head1 RETURN VALUES
CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return
1 for success and 0 for failure.
1 for success and 0 for failure.
CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs
or NULL if there are none or an error occurs. The only error which will occur
@@ -54,13 +56,17 @@ in practice is if the B<cms> type is invalid.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>,
L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_encrypt(3)|CMS_encrypt(3)>
L<ERR_get_error(3)>,
L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 HISTORY
=head1 COPYRIGHT
CMS_add0_cert(), CMS_add1_cert(), CMS_get1_certs(), CMS_add0_crl()
and CMS_get1_crls() were all first added to OpenSSL 0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/crypto/CMS_add1_recipient_cert.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure
=head1 SYNOPSIS
@@ -51,12 +53,16 @@ occurs.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>,
L<CMS_final(3)|CMS_final(3)>,
L<ERR_get_error(3)>, L<CMS_decrypt(3)>,
L<CMS_final(3)>,
=head1 HISTORY
=head1 COPYRIGHT
CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL
0.9.8
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/crypto/CMS_add1_signer.pod
View File

@@ -1,8 +1,10 @@
=pod
=encoding utf8
=head1 NAME
CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure
=head1 SYNOPSIS
@@ -52,7 +54,7 @@ structure. An error occurs if a matching digest value cannot be found to copy.
The returned CMS_ContentInfo structure will be valid and finalized when this
flag is set.
If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the
If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the
CMS_SignerInfo structure will not be finalized so additional attributes
can be added. In this case an explicit call to CMS_SignerInfo_sign() is
needed to finalize it.
@@ -81,7 +83,7 @@ If any of these algorithms is not available then it will not be included: for ex
not loaded.
CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added, this can be used to set additional attributes
structure just added, this can be used to set additional attributes
before it is finalized.
=head1 RETURN VALUES
@@ -91,11 +93,16 @@ structure just added or NULL if an error occurs.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_final(3)|CMS_final(3)>,
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_final(3)>,
=head1 HISTORY
=head1 COPYRIGHT
CMS_add1_signer() was added to OpenSSL 0.9.8
Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/CMS_compress.pod
View File

@@ -1,5 +1,7 @@
=pod
=encoding utf8
=head1 NAME
CMS_compress - create a CMS CompressedData structure
@@ -63,11 +65,19 @@ occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_uncompress(3)|CMS_uncompress(3)>
L<ERR_get_error(3)>, L<CMS_uncompress(3)>
=head1 HISTORY
CMS_compress() was added to OpenSSL 0.9.8
The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0.
The B<CMS_STREAM> flag was added in OpenSSL 1.0.0.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

Some files were not shown because too many files have changed in this diff Show More