mirror of
https://github.com/Astatin3/meteorbot-old.git
synced 2026-06-09 08:38:07 -06:00
Initial commit
This commit is contained in:
Astatin3
@@ -0,0 +1,110 @@
|
||||
<DRAFT!>
|
||||
HOWTO certificates
|
||||
|
||||
1. Introduction
|
||||
|
||||
How you handle certificates depends a great deal on what your role is.
|
||||
Your role can be one or several of:
|
||||
|
||||
- User of some client application
|
||||
- User of some server application
|
||||
- Certificate authority
|
||||
|
||||
This file is for users who wish to get a certificate of their own.
|
||||
Certificate authorities should read https://www.openssl.org/docs/apps/ca.html.
|
||||
|
||||
In all the cases shown below, the standard configuration file, as
|
||||
compiled into openssl, will be used. You may find it in /etc/,
|
||||
/usr/local/ssl/ or somewhere else. By default the file is named
|
||||
openssl.cnf and is described at https://www.openssl.org/docs/apps/config.html.
|
||||
You can specify a different configuration file using the
|
||||
'-config {file}' argument with the commands shown below.
|
||||
|
||||
|
||||
2. Relationship with keys
|
||||
|
||||
Certificates are related to public key cryptography by containing a
|
||||
public key. To be useful, there must be a corresponding private key
|
||||
somewhere. With OpenSSL, public keys are easily derived from private
|
||||
keys, so before you create a certificate or a certificate request, you
|
||||
need to create a private key.
|
||||
|
||||
Private keys are generated with 'openssl genrsa -out privkey.pem' if
|
||||
you want a RSA private key, or if you want a DSA private key:
|
||||
'openssl dsaparam -out dsaparam.pem 2048; openssl gendsa -out privkey.pem dsaparam.pem'.
|
||||
|
||||
The private keys created by these commands are not passphrase protected;
|
||||
it might or might not be the desirable thing. Further information on how to
|
||||
create private keys can be found at https://www.openssl.org/docs/HOWTO/keys.txt.
|
||||
The rest of this text assumes you have a private key in the file privkey.pem.
|
||||
|
||||
|
||||
3. Creating a certificate request
|
||||
|
||||
To create a certificate, you need to start with a certificate request
|
||||
(or, as some certificate authorities like to put it, "certificate
|
||||
signing request", since that's exactly what they do, they sign it and
|
||||
give you the result back, thus making it authentic according to their
|
||||
policies). A certificate request is sent to a certificate authority
|
||||
to get it signed into a certificate. You can also sign the certificate
|
||||
yourself if you have your own certificate authority or create a
|
||||
self-signed certificate (typically for testing purpose).
|
||||
|
||||
The certificate request is created like this:
|
||||
|
||||
openssl req -new -key privkey.pem -out cert.csr
|
||||
|
||||
Now, cert.csr can be sent to the certificate authority, if they can
|
||||
handle files in PEM format. If not, use the extra argument '-outform'
|
||||
followed by the keyword for the format to use (see another HOWTO
|
||||
<formats.txt?>). In some cases, -outform does not let you output the
|
||||
certificate request in the right format and you will have to use one
|
||||
of the various other commands that are exposed by openssl (or get
|
||||
creative and use a combination of tools).
|
||||
|
||||
The certificate authority performs various checks (according to their
|
||||
policies) and usually waits for payment from you. Once that is
|
||||
complete, they send you your new certificate.
|
||||
|
||||
Section 5 will tell you more on how to handle the certificate you
|
||||
received.
|
||||
|
||||
|
||||
4. Creating a self-signed test certificate
|
||||
|
||||
You can create a self-signed certificate if you don't want to deal
|
||||
with a certificate authority, or if you just want to create a test
|
||||
certificate for yourself. This is similar to creating a certificate
|
||||
request, but creates a certificate instead of a certificate request.
|
||||
This is NOT the recommended way to create a CA certificate, see
|
||||
https://www.openssl.org/docs/apps/ca.html.
|
||||
|
||||
openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
|
||||
|
||||
|
||||
5. What to do with the certificate
|
||||
|
||||
If you created everything yourself, or if the certificate authority
|
||||
was kind enough, your certificate is a raw DER thing in PEM format.
|
||||
Your key most definitely is if you have followed the examples above.
|
||||
However, some (most?) certificate authorities will encode them with
|
||||
things like PKCS7 or PKCS12, or something else. Depending on your
|
||||
applications, this may be perfectly OK, it all depends on what they
|
||||
know how to decode. If not, there are a number of OpenSSL tools to
|
||||
convert between some (most?) formats.
|
||||
|
||||
So, depending on your application, you may have to convert your
|
||||
certificate and your key to various formats, most often also putting
|
||||
them together into one file. The ways to do this is described in
|
||||
another HOWTO <formats.txt?>, I will just mention the simplest case.
|
||||
In the case of a raw DER thing in PEM format, and assuming that's all
|
||||
right for your applications, simply concatenating the certificate and
|
||||
the key into a new file and using that one should be enough. With
|
||||
some applications, you don't even have to do that.
|
||||
|
||||
|
||||
By now, you have your certificate and your private key and can start
|
||||
using applications that depend on it.
|
||||
|
||||
--
|
||||
Richard Levitte
|
||||
@@ -0,0 +1,105 @@
|
||||
<DRAFT!>
|
||||
HOWTO keys
|
||||
|
||||
1. Introduction
|
||||
|
||||
Keys are the basis of public key algorithms and PKI. Keys usually
|
||||
come in pairs, with one half being the public key and the other half
|
||||
being the private key. With OpenSSL, the private key contains the
|
||||
public key information as well, so a public key doesn't need to be
|
||||
generated separately.
|
||||
|
||||
Public keys come in several flavors, using different cryptographic
|
||||
algorithms. The most popular ones associated with certificates are
|
||||
RSA and DSA, and this HOWTO will show how to generate each of them.
|
||||
|
||||
|
||||
2. To generate a RSA key
|
||||
|
||||
A RSA key can be used both for encryption and for signing.
|
||||
|
||||
Generating a key for the RSA algorithm is quite easy, all you have to
|
||||
do is the following:
|
||||
|
||||
openssl genrsa -des3 -out privkey.pem 2048
|
||||
|
||||
With this variant, you will be prompted for a protecting password. If
|
||||
you don't want your key to be protected by a password, remove the flag
|
||||
'-des3' from the command line above.
|
||||
|
||||
The number 2048 is the size of the key, in bits. Today, 2048 or
|
||||
higher is recommended for RSA keys, as fewer amount of bits is
|
||||
consider insecure or to be insecure pretty soon.
|
||||
|
||||
|
||||
3. To generate a DSA key
|
||||
|
||||
A DSA key can be used for signing only. It is important to
|
||||
know what a certificate request with a DSA key can really be used for.
|
||||
|
||||
Generating a key for the DSA algorithm is a two-step process. First,
|
||||
you have to generate parameters from which to generate the key:
|
||||
|
||||
openssl dsaparam -out dsaparam.pem 2048
|
||||
|
||||
The number 2048 is the size of the key, in bits. Today, 2048 or
|
||||
higher is recommended for DSA keys, as fewer amount of bits is
|
||||
consider insecure or to be insecure pretty soon.
|
||||
|
||||
When that is done, you can generate a key using the parameters in
|
||||
question (actually, several keys can be generated from the same
|
||||
parameters):
|
||||
|
||||
openssl gendsa -des3 -out privkey.pem dsaparam.pem
|
||||
|
||||
With this variant, you will be prompted for a protecting password. If
|
||||
you don't want your key to be protected by a password, remove the flag
|
||||
'-des3' from the command line above.
|
||||
|
||||
|
||||
4. To generate an EC key
|
||||
|
||||
An EC key can be used both for key agreement (ECDH) and signing (ECDSA).
|
||||
|
||||
Generating a key for ECC is similar to generating a DSA key. These are
|
||||
two-step processes. First, you have to get the EC parameters from which
|
||||
the key will be generated:
|
||||
|
||||
openssl ecparam -name prime256v1 -out prime256v1.pem
|
||||
|
||||
The prime256v1, or NIST P-256, which stands for 'X9.62/SECG curve over
|
||||
a 256-bit prime field', is the name of an elliptic curve which generates the
|
||||
parameters. You can use the following command to list all supported curves:
|
||||
|
||||
openssl ecparam -list_curves
|
||||
|
||||
When that is done, you can generate a key using the created parameters (several
|
||||
keys can be produced from the same parameters):
|
||||
|
||||
openssl genpkey -des3 -paramfile prime256v1.pem -out private.key
|
||||
|
||||
With this variant, you will be prompted for a password to protect your key.
|
||||
If you don't want your key to be protected by a password, remove the flag
|
||||
'-des3' from the command line above.
|
||||
|
||||
You can also directly generate the key in one step:
|
||||
|
||||
openssl ecparam -genkey -name prime256v1 -out private.key
|
||||
|
||||
or
|
||||
|
||||
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256
|
||||
|
||||
|
||||
5. NOTE
|
||||
|
||||
If you intend to use the key together with a server certificate,
|
||||
it may be reasonable to avoid protecting it with a password, since
|
||||
otherwise someone would have to type in the password every time the
|
||||
server needs to access the key.
|
||||
|
||||
For X25519 and X448, it's treated as a distinct algorithm but not as one of
|
||||
the curves listed with 'ecparam -list_curves' option. You can use
|
||||
the following command to generate an X25519 key:
|
||||
|
||||
openssl genpkey -algorithm X25519 -out xkey.pem
|
||||
@@ -0,0 +1,27 @@
|
||||
|
||||
README This file
|
||||
|
||||
fingerprints.txt
|
||||
PGP fingerprints of authorised release signers
|
||||
|
||||
standards.txt
|
||||
Moved to the web, https://www.openssl.org/docs/standards.html
|
||||
|
||||
HOWTO/
|
||||
A few how-to documents; not necessarily up-to-date
|
||||
|
||||
man1/
|
||||
The openssl command-line tools; start with openssl.pod
|
||||
|
||||
man3/
|
||||
The SSL library and the crypto library
|
||||
|
||||
man5/
|
||||
File formats
|
||||
|
||||
man7/
|
||||
Overviews; start with crypto.pod and ssl.pod, for example
|
||||
Algorithm specific EVP_PKEY documentation.
|
||||
|
||||
Formatted versions of the manpages (apps,ssl,crypto) can be found at
|
||||
https://www.openssl.org/docs/manpages.html
|
||||
@@ -0,0 +1,15 @@
|
||||
;;; This is an example of what a .dir-locals.el suitable for OpenSSL
|
||||
;;; development could look like.
|
||||
;;;
|
||||
;;; Apart from setting the CC mode style to "OpenSSL-II", it also
|
||||
;;; makes sure that tabs are never used for indentation in any file,
|
||||
;;; and that the fill column is 78.
|
||||
;;;
|
||||
;;; For more information see (info "(emacs) Directory Variables")
|
||||
|
||||
((nil
|
||||
(indent-tabs-mode . nil)
|
||||
(fill-column . 70)
|
||||
)
|
||||
(c-mode
|
||||
(c-file-style . "OpenSSL-II")))
|
||||
@@ -0,0 +1,24 @@
|
||||
Fingerprints for Signing Releases
|
||||
|
||||
OpenSSL releases are signed with PGP/GnuPG keys. This file contains
|
||||
the fingerprints of team members who are "authorized" to sign the
|
||||
next release.
|
||||
|
||||
The signature is a detached cleartxt signature, with the same name
|
||||
as the release but with ".asc" appended. For example, release
|
||||
1.0.1h can be found in openssl-1.0.1h.tar.gz with the signature
|
||||
in the file named openssl-1.0.1h.tar.gz.asc.
|
||||
|
||||
The following is the list of fingerprints for the keys that are
|
||||
currently in use to sign OpenSSL distributions:
|
||||
|
||||
pub 4096R/7DF9EE8C 2014-10-04
|
||||
Key fingerprint = 7953 AC1F BC3D C8B3 B292 393E D5E9 E43F 7DF9 EE8C
|
||||
uid Richard Levitte <richard@opensslfoundation.com>
|
||||
uid Richard Levitte <levitte@openssl.org>
|
||||
uid Richard Levitte <richard@openssl.com>
|
||||
|
||||
pub 2048R/0E604491 2013-04-30
|
||||
Key fingerprint = 8657 ABB2 60F0 56B1 E519 0839 D9C4 D26D 0E60 4491
|
||||
uid Matt Caswell <matt@openssl.org>
|
||||
uid Matt Caswell <frodo@baggins.org>
|
||||
@@ -0,0 +1,214 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
CA.pl - friendlier interface for OpenSSL certificate programs
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<CA.pl>
|
||||
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.
|
||||
It is intended to simplify the process of certificate creation and management
|
||||
by the use of some simple options.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<?>, B<-h>, B<-help>
|
||||
|
||||
Prints a usage message.
|
||||
|
||||
=item B<-newcert>
|
||||
|
||||
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<openssl 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<openssl req> command below the hood.
|
||||
|
||||
=item B<-newreq-nodes>
|
||||
|
||||
Is like B<-newreq> except that the private key will not be encrypted.
|
||||
Uses B<openssl req> command.
|
||||
|
||||
=item B<-newca>
|
||||
|
||||
Creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert>
|
||||
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<openssl req> and B<openssl ca> commands are get invoked.
|
||||
|
||||
=item B<-pkcs12>
|
||||
|
||||
Create a PKCS#12 file containing the user certificate, private key and CA
|
||||
certificate. It expects the user certificate and private key to be in the
|
||||
file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem,
|
||||
it creates a file "newcert.p12". This command can thus be called after the
|
||||
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<openssl pkcs12> command.
|
||||
|
||||
=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. Leverages B<openssl ca> command.
|
||||
|
||||
=item B<-signCA>
|
||||
|
||||
This option is the same as the B<-sign> 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<openssl 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<openssl x509> and B<openssl ca> commands.
|
||||
|
||||
=item B<-crl>
|
||||
|
||||
Generate a CRL. Executes B<openssl 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<openssl 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". Invokes B<openssl verify> command.
|
||||
|
||||
=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> <extra-params>
|
||||
|
||||
The purpose of these parameters is to allow optional parameters to be supplied
|
||||
to B<openssl> that this command executes. The B<-extra-cmd> are specific to the
|
||||
option being used and the B<openssl> command getting invoked. For example
|
||||
when this command invokes B<openssl req> extra parameters can be passed on
|
||||
with the B<-extra-req> parameter. The
|
||||
B<openssl> commands being invoked per option are documented below.
|
||||
Users should consult B<openssl> command documentation for more information.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Create a CA hierarchy:
|
||||
|
||||
CA.pl -newca
|
||||
|
||||
Complete certificate creation example: create a CA, create a request, sign
|
||||
the request and finally create a PKCS#12 file containing it.
|
||||
|
||||
CA.pl -newca
|
||||
CA.pl -newreq
|
||||
CA.pl -sign
|
||||
CA.pl -pkcs12 "My Test Certificate"
|
||||
|
||||
=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)> command
|
||||
directly. The following example shows the steps that would typically be taken.
|
||||
|
||||
Create some DSA parameters:
|
||||
|
||||
openssl 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
|
||||
|
||||
Create the CA directories and files:
|
||||
|
||||
CA.pl -newca
|
||||
|
||||
enter cacert.pem when prompted for the CA filename.
|
||||
|
||||
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
|
||||
|
||||
Sign the request:
|
||||
|
||||
CA.pl -sign
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Most of the filenames mentioned can be modified by editing the B<CA.pl> script.
|
||||
|
||||
If the demoCA directory already exists then the B<-newca> command will not
|
||||
overwrite it and will do nothing. This can happen if a previous call using
|
||||
the B<-newca> option terminated abnormally. To get the correct behaviour
|
||||
delete the demoCA directory if it already exists.
|
||||
|
||||
Under some environments it may not be possible to run the B<CA.pl> script
|
||||
directly (for example Win32) and the default configuration file location may
|
||||
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
|
||||
the correct path of the configuration file.
|
||||
|
||||
The script is intended as a simple front end for the B<openssl> 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.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>,
|
||||
L<config(5)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,215 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-asn1parse,
|
||||
asn1parse - ASN.1 parsing tool
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<asn1parse>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-noout>]
|
||||
[B<-offset number>]
|
||||
[B<-length number>]
|
||||
[B<-i>]
|
||||
[B<-oid filename>]
|
||||
[B<-dump>]
|
||||
[B<-dlimit num>]
|
||||
[B<-strparse offset>]
|
||||
[B<-genstr string>]
|
||||
[B<-genconf file>]
|
||||
[B<-strictpem>]
|
||||
[B<-item name>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<asn1parse> command is a diagnostic utility that can parse ASN.1
|
||||
structures. It can also be used to extract data from ASN.1 formatted data.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=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
|
||||
encoded.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
The input file, default is standard input.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
Output file to place the DER encoded data into. If this
|
||||
option is not present then no data will be output. This is most useful when
|
||||
combined with the B<-strparse> option.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
Don't output the parsed version of the input file.
|
||||
|
||||
=item B<-offset number>
|
||||
|
||||
Starting offset to begin parsing, default is start of file.
|
||||
|
||||
=item B<-length number>
|
||||
|
||||
Number of bytes to parse, default is until end of file.
|
||||
|
||||
=item B<-i>
|
||||
|
||||
Indents the output according to the "depth" of the structures.
|
||||
|
||||
=item B<-oid filename>
|
||||
|
||||
A file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
|
||||
file is described in the NOTES section below.
|
||||
|
||||
=item B<-dump>
|
||||
|
||||
Dump unknown data in hex format.
|
||||
|
||||
=item B<-dlimit num>
|
||||
|
||||
Like B<-dump>, but only the first B<num> bytes are output.
|
||||
|
||||
=item B<-strparse offset>
|
||||
|
||||
Parse the contents octets of the ASN.1 object starting at B<offset>. This
|
||||
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)> 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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-item name>
|
||||
|
||||
Attempt to decode and print the data as B<ASN1_ITEM name>. This can be used to
|
||||
print out the fields of any supported ASN.1 structure if the type is known.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Output
|
||||
|
||||
The output will typically contain lines like this:
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
.....
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
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>
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Parse a file:
|
||||
|
||||
openssl asn1parse -in file.pem
|
||||
|
||||
Parse a DER file:
|
||||
|
||||
openssl asn1parse -inform DER -in file.der
|
||||
|
||||
Generate a simple UTF8String:
|
||||
|
||||
openssl 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
|
||||
|
||||
Generate using a config file:
|
||||
|
||||
openssl asn1parse -genconf asn1.cnf -noout -out asn1.der
|
||||
|
||||
Example config file:
|
||||
|
||||
asn1=SEQUENCE:seq_sect
|
||||
|
||||
[seq_sect]
|
||||
|
||||
field1=BOOL:TRUE
|
||||
field2=EXP:0, UTF8:some random string
|
||||
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
There should be options to change the format of output lines. The output of some
|
||||
ASN.1 types is not well handled (if at all).
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ASN1_generate_nconf(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 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
|
||||
@@ -0,0 +1,769 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-ca,
|
||||
ca - sample minimal CA application
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> 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>]
|
||||
[B<-crl_hold instruction>]
|
||||
[B<-crl_compromise time>]
|
||||
[B<-crl_CA_compromise time>]
|
||||
[B<-crldays days>]
|
||||
[B<-crlhours hours>]
|
||||
[B<-crlexts section>]
|
||||
[B<-startdate date>]
|
||||
[B<-enddate date>]
|
||||
[B<-days arg>]
|
||||
[B<-md arg>]
|
||||
[B<-policy arg>]
|
||||
[B<-keyfile arg>]
|
||||
[B<-keyform PEM|DER>]
|
||||
[B<-key arg>]
|
||||
[B<-passin arg>]
|
||||
[B<-cert file>]
|
||||
[B<-selfsign>]
|
||||
[B<-in file>]
|
||||
[B<-out file>]
|
||||
[B<-notext>]
|
||||
[B<-outdir dir>]
|
||||
[B<-infiles>]
|
||||
[B<-spkac file>]
|
||||
[B<-ss_cert file>]
|
||||
[B<-preserveDN>]
|
||||
[B<-noemailDN>]
|
||||
[B<-batch>]
|
||||
[B<-msie_hack>]
|
||||
[B<-extensions section>]
|
||||
[B<-extfile section>]
|
||||
[B<-engine id>]
|
||||
[B<-subj arg>]
|
||||
[B<-utf8>]
|
||||
[B<-sigopt nm:v>]
|
||||
[B<-create_serial>]
|
||||
[B<-rand_serial>]
|
||||
[B<-multivalue-rdn>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<ca> command is a minimal CA application. It can be used
|
||||
to sign certificate requests in a variety of forms and generate
|
||||
CRLs it also maintains a text database of issued certificates
|
||||
and their status.
|
||||
|
||||
The options descriptions will be divided into each purpose.
|
||||
|
||||
=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.
|
||||
Optional; for a description of the default value,
|
||||
see L<openssl(1)/COMMAND SUMMARY>.
|
||||
|
||||
=item B<-name section>
|
||||
|
||||
Specifies the configuration file section to use (overrides
|
||||
B<default_ca> in the B<ca> section).
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
An input filename containing a single certificate request to be
|
||||
signed by the CA.
|
||||
|
||||
=item B<-ss_cert filename>
|
||||
|
||||
A single self-signed certificate to be signed by the CA.
|
||||
|
||||
=item B<-spkac filename>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-infiles>
|
||||
|
||||
If present this should be the last option, all subsequent arguments
|
||||
are taken as the names of files containing certificate requests.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
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).
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-cert>
|
||||
|
||||
The CA certificate file.
|
||||
|
||||
=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.
|
||||
|
||||
=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<-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.
|
||||
|
||||
=item B<-selfsign>
|
||||
|
||||
Indicates the issued certificates are to be signed with the key
|
||||
the certificate requests were signed with (given with B<-keyfile>).
|
||||
Certificate requests signed with a different key are ignored. If
|
||||
B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
|
||||
ignored.
|
||||
|
||||
A consequence of using B<-selfsign> is that the self-signed
|
||||
certificate appears among the entries in the certificate database
|
||||
(see the configuration option B<database>), and uses the same
|
||||
serial number counter as all other certificates sign with the
|
||||
self-signed certificate.
|
||||
|
||||
=item B<-passin arg>
|
||||
|
||||
The key password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=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), or
|
||||
YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
|
||||
both formats, seconds SS and timezone Z must be present.
|
||||
|
||||
=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), or
|
||||
YYYYMMDDHHMMSSZ (the same as an ASN1 GeneralizedTime structure). In
|
||||
both formats, seconds SS and timezone Z must be present.
|
||||
|
||||
=item B<-days arg>
|
||||
|
||||
The number of days to certify the certificate for.
|
||||
|
||||
=item B<-md alg>
|
||||
|
||||
The message digest to use.
|
||||
Any digest supported by the OpenSSL B<dgst> command can be used. For signing
|
||||
algorithms that do not support a digest (i.e. Ed25519 and Ed448) any message
|
||||
digest that is set is ignored. This option also applies to CRLs.
|
||||
|
||||
=item B<-policy arg>
|
||||
|
||||
This option defines the CA "policy" to use. This is a section in
|
||||
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.
|
||||
|
||||
=item B<-msie_hack>
|
||||
|
||||
This is a deprecated option to make B<ca> work with very old versions of
|
||||
the IE certificate enrollment control "certenr3". It used UniversalStrings
|
||||
for almost everything. Since the old control has various security bugs
|
||||
its use is strongly discouraged.
|
||||
|
||||
=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
|
||||
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
|
||||
request DN, however, it is good policy just having the e-mail set into
|
||||
the altName extension of the certificate. When this option is set the
|
||||
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.
|
||||
|
||||
=item B<-batch>
|
||||
|
||||
This sets the batch mode. In this mode no questions will be asked
|
||||
and all certificates will be certified automatically.
|
||||
|
||||
=item B<-extensions section>
|
||||
|
||||
The section of the configuration file containing certificate extensions
|
||||
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
|
||||
L<x509v3_config(5)> manual page for details of the
|
||||
extension section format.
|
||||
|
||||
=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).
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<ca>
|
||||
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<-subj arg>
|
||||
|
||||
Supersedes subject name given in the request.
|
||||
The arg must be formatted as I</type0=value0/type1=value1/type2=...>.
|
||||
Keyword characters may be escaped by \ (backslash), and whitespace is retained.
|
||||
Empty values are permitted, but the corresponding type will not be included
|
||||
in the resulting certificate.
|
||||
|
||||
=item B<-utf8>
|
||||
|
||||
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.
|
||||
|
||||
=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.
|
||||
To get random serial numbers, use the B<-rand_serial> flag instead; this
|
||||
should only be used for simple error-recovery.
|
||||
|
||||
=item B<-rand_serial>
|
||||
|
||||
Generate a large random number to use as the serial number.
|
||||
This overrides any option or configuration to use a serial number file.
|
||||
|
||||
=item B<-multivalue-rdn>
|
||||
|
||||
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>
|
||||
|
||||
If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=back
|
||||
|
||||
=head1 CRL OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-gencrl>
|
||||
|
||||
This option generates a CRL based on information in the index file.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-crlhours num>
|
||||
|
||||
The number of hours before the next CRL is due.
|
||||
|
||||
=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>,
|
||||
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 practice B<removeFromCRL> is not particularly useful because it is only used
|
||||
in delta CRLs which are not currently implemented.
|
||||
|
||||
=item B<-crl_hold instruction>
|
||||
|
||||
This sets the CRL revocation reason code to B<certificateHold> and the hold
|
||||
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.
|
||||
|
||||
=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>.
|
||||
|
||||
=item B<-crl_CA_compromise time>
|
||||
|
||||
This is the same as B<crl_compromise> except the revocation reason is set to
|
||||
B<CACompromise>.
|
||||
|
||||
=item B<-crlexts section>
|
||||
|
||||
The section of the configuration file containing CRL extensions to
|
||||
include. If no CRL extension section is present then a V1 CRL is
|
||||
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)> manual page for details of the
|
||||
extension section format.
|
||||
|
||||
=back
|
||||
|
||||
=head1 CONFIGURATION FILE OPTIONS
|
||||
|
||||
The section of the configuration file containing options for B<ca>
|
||||
is found as follows: If the B<-name> command line option is used,
|
||||
then it names the section to be used. Otherwise the section to
|
||||
be used must be named in the B<default_ca> option of the B<ca> section
|
||||
of the configuration file (or in the default section of the
|
||||
configuration file). Besides B<default_ca>, the following options are
|
||||
read directly from the B<ca> section:
|
||||
RANDFILE
|
||||
preserve
|
||||
msie_hack
|
||||
With the exception of B<RANDFILE>, this is probably a bug and may
|
||||
change in future releases.
|
||||
|
||||
Many of the configuration file options are identical to command line
|
||||
options. Where the option is present in the configuration file
|
||||
and the command line the command line value is used. Where an
|
||||
option is described as mandatory then it must be present in
|
||||
the configuration file or the command line equivalent (if
|
||||
any) used.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<oid_file>
|
||||
|
||||
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.
|
||||
|
||||
=item B<oid_section>
|
||||
|
||||
This specifies a section in the configuration file containing extra
|
||||
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.
|
||||
|
||||
=item B<certificate>
|
||||
|
||||
The same as B<-cert>. It gives the file containing the CA
|
||||
certificate. Mandatory.
|
||||
|
||||
=item B<private_key>
|
||||
|
||||
Same as the B<-keyfile> option. The file containing the
|
||||
CA private key. Mandatory.
|
||||
|
||||
=item B<RANDFILE>
|
||||
|
||||
At startup the specified file is loaded into the random number generator,
|
||||
and at exit 256 bytes will be written to it.
|
||||
|
||||
=item B<default_days>
|
||||
|
||||
The same as the B<-days> option. The number of days to certify
|
||||
a certificate for.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<default_md>
|
||||
|
||||
The same as the B<-md> option. Mandatory except where the signing algorithm does
|
||||
not require a digest (i.e. Ed25519 and Ed448).
|
||||
|
||||
=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,
|
||||
it's recommended to use the value B<no>, especially if combined with
|
||||
the B<-selfsign> command line option.
|
||||
|
||||
Note that it is valid in some circumstances for certificates to be created
|
||||
without any subject. In the case where there are multiple certificates without
|
||||
subjects this does not count as a duplicate.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<x509_extensions>
|
||||
|
||||
The same as B<-extensions>.
|
||||
|
||||
=item B<crl_extensions>
|
||||
|
||||
The same as B<-crlexts>.
|
||||
|
||||
=item B<preserve>
|
||||
|
||||
The same as B<-preserveDN>
|
||||
|
||||
=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.
|
||||
|
||||
=item B<msie_hack>
|
||||
|
||||
The same as B<-msie_hack>
|
||||
|
||||
=item B<policy>
|
||||
|
||||
The same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
|
||||
for more information.
|
||||
|
||||
=item B<name_opt>, B<cert_opt>
|
||||
|
||||
These options allow the format used to display the certificate details
|
||||
when asking the user to confirm signing. All the options supported by
|
||||
the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
|
||||
here, except the B<no_signame> and B<no_sigdump> are permanently set
|
||||
and cannot be disabled (this is because the certificate signature cannot
|
||||
be displayed because the certificate has not been signed at this point).
|
||||
|
||||
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
|
||||
it only displays fields mentioned in the B<policy> section, mishandles
|
||||
multicharacter string types and does not display extensions.
|
||||
|
||||
=item B<copy_extensions>
|
||||
|
||||
Determines how extensions in certificate requests should be handled.
|
||||
If set to B<none> or this option is not present then extensions are
|
||||
ignored and not copied to the certificate. If set to B<copy> then any
|
||||
extensions present in the request that are not already present are copied
|
||||
to the certificate. If set to B<copyall> then all extensions in the
|
||||
request are copied to the certificate: if the extension is already present
|
||||
in the certificate it is deleted first. See the B<WARNINGS> section before
|
||||
using this option.
|
||||
|
||||
The main use of this option is to allow a certificate request to supply
|
||||
values for certain extensions such as subjectAltName.
|
||||
|
||||
=back
|
||||
|
||||
=head1 POLICY FORMAT
|
||||
|
||||
The policy section consists of a set of variables corresponding to
|
||||
certificate DN fields. If the value is "match" then the field value
|
||||
must match the same field in the CA certificate. If the value is
|
||||
"supplied" then it must be present. If the value is "optional" then
|
||||
it may be present. Any fields not mentioned in the policy section
|
||||
are silently deleted, unless the B<-preserveDN> option is set but
|
||||
this can be regarded more of a quirk than intended behaviour.
|
||||
|
||||
=head1 SPKAC FORMAT
|
||||
|
||||
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.
|
||||
It is however possible to create SPKACs using the B<spkac> utility.
|
||||
|
||||
The file should contain the variable SPKAC set to the value of
|
||||
the SPKAC and also the required DN components as name value pairs.
|
||||
If you need to include the same component twice then it can be
|
||||
preceded by a number and a '.'.
|
||||
|
||||
When processing SPKAC format, the output is DER if the B<-out>
|
||||
flag is used, but PEM format if sending to stdout or the B<-outdir>
|
||||
flag is used.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Note: these examples assume that the B<ca> directory structure is
|
||||
already set up and the relevant files already exist. This usually
|
||||
involves creating a CA certificate and private key with B<req>, a
|
||||
serial number file and an empty index file and placing them in
|
||||
the relevant directories.
|
||||
|
||||
To use the sample configuration file below the directories demoCA,
|
||||
demoCA/private and demoCA/newcerts would be created. The CA
|
||||
certificate would be copied to demoCA/cacert.pem and its private
|
||||
key to demoCA/private/cakey.pem. A file demoCA/serial would be
|
||||
created containing for example "01" and the empty index file
|
||||
demoCA/index.txt.
|
||||
|
||||
|
||||
Sign a certificate request:
|
||||
|
||||
openssl 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
|
||||
|
||||
Generate a CRL
|
||||
|
||||
openssl ca -gencrl -out crl.pem
|
||||
|
||||
Sign several requests:
|
||||
|
||||
openssl ca -infiles req1.pem req2.pem req3.pem
|
||||
|
||||
Certify a Netscape SPKAC:
|
||||
|
||||
openssl 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
|
||||
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
|
||||
|
||||
certificate = $dir/cacert.pem # The CA cert
|
||||
serial = $dir/serial # serial no file
|
||||
#rand_serial = yes # for random serial#'s
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
[ policy_any ]
|
||||
countryName = supplied
|
||||
stateOrProvinceName = optional
|
||||
organizationName = optional
|
||||
organizationalUnitName = optional
|
||||
commonName = supplied
|
||||
emailAddress = optional
|
||||
|
||||
=head1 FILES
|
||||
|
||||
Note: the location of all files can change either by compile time options,
|
||||
configuration file entries, environment variables or command line options.
|
||||
The values below reflect the default values.
|
||||
|
||||
/usr/local/ssl/lib/openssl.cnf - master configuration file
|
||||
./demoCA - main CA directory
|
||||
./demoCA/cacert.pem - CA certificate
|
||||
./demoCA/private/cakey.pem - CA private key
|
||||
./demoCA/serial - CA serial number file
|
||||
./demoCA/serial.old - CA serial number backup file
|
||||
./demoCA/index.txt - CA text database file
|
||||
./demoCA/index.txt.old - CA text database backup file
|
||||
./demoCA/certs - certificate output file
|
||||
./demoCA/.rnd - CA random seed information
|
||||
|
||||
=head1 RESTRICTIONS
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
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 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
|
||||
enforce the absence of the EMAIL field within the DN, as suggested by
|
||||
RFCs, regardless the contents of the request' subject the B<-noemailDN>
|
||||
option can be used. The behaviour should be more friendly and
|
||||
configurable.
|
||||
|
||||
Canceling some commands by refusing to certify a certificate can
|
||||
create an empty file.
|
||||
|
||||
=head1 WARNINGS
|
||||
|
||||
The B<ca> command is quirky and at times downright unfriendly.
|
||||
|
||||
The B<ca> utility was originally meant as an example of how to do things
|
||||
in a CA. It was not supposed to be used as a full blown CA itself:
|
||||
nevertheless some people are using it for this purpose.
|
||||
|
||||
The B<ca> command is effectively a single user command: no locking is
|
||||
done on the various files and attempts to run more than one B<ca> command
|
||||
on the same database can have unpredictable results.
|
||||
|
||||
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 requester
|
||||
a valid CA certificate.
|
||||
|
||||
This situation can be avoided by setting B<copy_extensions> to B<copy>
|
||||
and including basicConstraints with CA:FALSE in the configuration file.
|
||||
Then if the request contains a basicConstraints extension it will be
|
||||
ignored.
|
||||
|
||||
It is advisable to also include values for other extensions such
|
||||
as B<keyUsage> to prevent a request supplying its own values.
|
||||
|
||||
Additional restrictions can be placed on the CA certificate itself.
|
||||
For example if the CA certificate has:
|
||||
|
||||
basicConstraints = CA:TRUE, pathlen:0
|
||||
|
||||
then even if a certificate is issued with CA:TRUE it will not be valid.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
Since OpenSSL 1.1.1, the program follows RFC5280. Specifically,
|
||||
certificate validity period (specified by any of B<-startdate>,
|
||||
B<-enddate> and B<-days>) will be encoded as UTCTime if the dates are
|
||||
earlier than year 2049 (included), and as GeneralizedTime if the dates
|
||||
are in year 2050 or later.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
|
||||
L<config(5)>, L<x509v3_config(5)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,776 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-ciphers,
|
||||
ciphers - SSL cipher display and cipher list tool
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<ciphers>
|
||||
[B<-help>]
|
||||
[B<-s>]
|
||||
[B<-v>]
|
||||
[B<-V>]
|
||||
[B<-ssl3>]
|
||||
[B<-tls1>]
|
||||
[B<-tls1_1>]
|
||||
[B<-tls1_2>]
|
||||
[B<-tls1_3>]
|
||||
[B<-s>]
|
||||
[B<-psk>]
|
||||
[B<-srp>]
|
||||
[B<-stdname>]
|
||||
[B<-convert name>]
|
||||
[B<-ciphersuites val>]
|
||||
[B<cipherlist>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<ciphers> command converts textual OpenSSL cipher lists into ordered
|
||||
SSL cipher preference lists. It can be used as a test tool to determine
|
||||
the appropriate cipherlist.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-psk>
|
||||
|
||||
When combined with B<-s> includes cipher suites which require PSK.
|
||||
|
||||
=item B<-srp>
|
||||
|
||||
When combined with B<-s> includes cipher suites which require SRP.
|
||||
|
||||
=item B<-v>
|
||||
|
||||
Verbose output: For each cipher suite, list details as provided by
|
||||
L<SSL_CIPHER_description(3)>.
|
||||
|
||||
=item B<-V>
|
||||
|
||||
Like B<-v>, but include the official cipher suite values in hex.
|
||||
|
||||
=item B<-tls1_3>, B<-tls1_2>, B<-tls1_1>, B<-tls1>, B<-ssl3>
|
||||
|
||||
In combination with the B<-s> option, list the ciphers which could be used if
|
||||
the specified protocol were negotiated.
|
||||
Note that not all protocols and flags may be available, depending on how
|
||||
OpenSSL was built.
|
||||
|
||||
=item B<-stdname>
|
||||
|
||||
Precede each cipher suite by its standard name.
|
||||
|
||||
=item B<-convert name>
|
||||
|
||||
Convert a standard cipher B<name> to its OpenSSL name.
|
||||
|
||||
=item B<-ciphersuites val>
|
||||
|
||||
Sets the list of TLSv1.3 ciphersuites. This list will be combined with any
|
||||
TLSv1.2 and below ciphersuites that have been configured. The format for this
|
||||
list is a simple colon (":") separated list of TLSv1.3 ciphersuite names. By
|
||||
default this value is:
|
||||
|
||||
TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256
|
||||
|
||||
=item B<cipherlist>
|
||||
|
||||
A cipher list of TLSv1.2 and below ciphersuites to convert to a cipher
|
||||
preference list. This list will be combined with any TLSv1.3 ciphersuites that
|
||||
have been configured. If it is not included then the default cipher list will be
|
||||
used. The format is described below.
|
||||
|
||||
=back
|
||||
|
||||
=head1 CIPHER LIST FORMAT
|
||||
|
||||
The cipher list consists of one or more I<cipher strings> separated by colons.
|
||||
Commas or spaces are also acceptable separators but colons are normally used.
|
||||
|
||||
The actual cipher string can take several different forms.
|
||||
|
||||
It can consist of a single cipher suite such as B<RC4-SHA>.
|
||||
|
||||
It can represent a list of cipher suites containing a certain algorithm, or
|
||||
cipher suites of a certain type. For example B<SHA1> represents all ciphers
|
||||
suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3
|
||||
algorithms.
|
||||
|
||||
Lists of cipher suites can be combined in a single cipher string using the
|
||||
B<+> character. This is used as a logical B<and> operation. For example
|
||||
B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES
|
||||
algorithms.
|
||||
|
||||
Each cipher string can be optionally preceded by the characters B<!>,
|
||||
B<-> or B<+>.
|
||||
|
||||
If B<!> is used then the ciphers are permanently deleted from the list.
|
||||
The ciphers deleted can never reappear in the list even if they are
|
||||
explicitly stated.
|
||||
|
||||
If B<-> is used then the ciphers are deleted from the list, but some or
|
||||
all of the ciphers can be added again by later options.
|
||||
|
||||
If B<+> is used then the ciphers are moved to the end of the list. This
|
||||
option doesn't add any new ciphers it just moves matching existing ones.
|
||||
|
||||
If none of these characters is present then the string is just interpreted
|
||||
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.
|
||||
|
||||
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>, which should be a number between zero and five, inclusive.
|
||||
See L<SSL_CTX_set_security_level> for a description of what each level means.
|
||||
|
||||
The cipher list can be prefixed with the B<DEFAULT> keyword, which enables
|
||||
the default cipher list as defined below. Unlike cipher strings,
|
||||
this prefix may not be combined with other strings using B<+> character.
|
||||
For example, B<DEFAULT+DES> is not valid.
|
||||
|
||||
The content of the default list is determined at compile time and normally
|
||||
corresponds to B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>.
|
||||
|
||||
=head1 CIPHER STRINGS
|
||||
|
||||
The following is a list of all permitted cipher strings and their meanings.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<COMPLEMENTOFDEFAULT>
|
||||
|
||||
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 cipher suites are not built into OpenSSL by
|
||||
default (see the enable-weak-ssl-ciphers option to Configure).
|
||||
|
||||
=item B<ALL>
|
||||
|
||||
All cipher suites except the B<eNULL> ciphers (which must be explicitly enabled
|
||||
if needed).
|
||||
As of OpenSSL 1.0.0, the B<ALL> cipher suites are sensibly ordered by default.
|
||||
|
||||
=item B<COMPLEMENTOFALL>
|
||||
|
||||
The cipher suites not enabled by B<ALL>, currently B<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.
|
||||
|
||||
=item B<MEDIUM>
|
||||
|
||||
"Medium" encryption cipher suites, currently some of those using 128 bit
|
||||
encryption.
|
||||
|
||||
=item B<LOW>
|
||||
|
||||
"Low" encryption cipher suites, currently those using 64 or 56 bit
|
||||
encryption algorithms but excluding export cipher suites. All these
|
||||
cipher suites have been removed as of OpenSSL 1.1.0.
|
||||
|
||||
=item B<eNULL>, B<NULL>
|
||||
|
||||
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.
|
||||
|
||||
=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 "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<aRSA>, B<RSA>
|
||||
|
||||
Cipher suites using RSA key exchange or authentication. B<RSA> is an alias for
|
||||
B<kRSA>.
|
||||
|
||||
=item B<kDHr>, B<kDHd>, B<kDH>
|
||||
|
||||
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 OpenSSL 1.1.0.
|
||||
|
||||
=item B<kDHE>, B<kEDH>, B<DH>
|
||||
|
||||
Cipher suites using ephemeral DH key agreement, including anonymous cipher
|
||||
suites.
|
||||
|
||||
=item B<DHE>, B<EDH>
|
||||
|
||||
Cipher suites using authenticated ephemeral DH key agreement.
|
||||
|
||||
=item B<ADH>
|
||||
|
||||
Anonymous DH cipher suites, note that this does not include anonymous Elliptic
|
||||
Curve DH (ECDH) cipher suites.
|
||||
|
||||
=item B<kEECDH>, B<kECDHE>, B<ECDH>
|
||||
|
||||
Cipher suites using ephemeral ECDH key agreement, including anonymous
|
||||
cipher suites.
|
||||
|
||||
=item B<ECDHE>, B<EECDH>
|
||||
|
||||
Cipher suites using authenticated ephemeral ECDH key agreement.
|
||||
|
||||
=item B<AECDH>
|
||||
|
||||
Anonymous Elliptic Curve Diffie-Hellman cipher suites.
|
||||
|
||||
=item B<aDSS>, B<DSS>
|
||||
|
||||
Cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
|
||||
|
||||
=item B<aDH>
|
||||
|
||||
Cipher suites effectively using DH authentication, i.e. the certificates carry
|
||||
DH keys.
|
||||
All these cipher suites have been removed in OpenSSL 1.1.0.
|
||||
|
||||
=item B<aECDSA>, B<ECDSA>
|
||||
|
||||
Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
|
||||
keys.
|
||||
|
||||
=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3>
|
||||
|
||||
Lists cipher suites which are only supported in at least TLS v1.2, TLS v1.0 or
|
||||
SSL v3.0 respectively.
|
||||
Note: there are no cipher suites 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 cipher suites 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<AES128>, B<AES256>, B<AES>
|
||||
|
||||
cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
|
||||
|
||||
=item B<AESGCM>
|
||||
|
||||
AES in Galois Counter Mode (GCM): these cipher suites are only supported
|
||||
in TLS v1.2.
|
||||
|
||||
=item B<AESCCM>, B<AESCCM8>
|
||||
|
||||
AES in Cipher Block Chaining - Message Authentication Mode (CCM): these
|
||||
cipher suites 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.
|
||||
|
||||
=item B<ARIA128>, B<ARIA256>, B<ARIA>
|
||||
|
||||
Cipher suites using 128 bit ARIA, 256 bit ARIA or either 128 or 256 bit
|
||||
ARIA.
|
||||
|
||||
=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
|
||||
|
||||
Cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
|
||||
CAMELLIA.
|
||||
|
||||
=item B<CHACHA20>
|
||||
|
||||
Cipher suites using ChaCha20.
|
||||
|
||||
=item B<3DES>
|
||||
|
||||
Cipher suites using triple DES.
|
||||
|
||||
=item B<DES>
|
||||
|
||||
Cipher suites using DES (not triple DES).
|
||||
All these cipher suites have been removed in OpenSSL 1.1.0.
|
||||
|
||||
=item B<RC4>
|
||||
|
||||
Cipher suites using RC4.
|
||||
|
||||
=item B<RC2>
|
||||
|
||||
Cipher suites using RC2.
|
||||
|
||||
=item B<IDEA>
|
||||
|
||||
Cipher suites using IDEA.
|
||||
|
||||
=item B<SEED>
|
||||
|
||||
Cipher suites using SEED.
|
||||
|
||||
=item B<MD5>
|
||||
|
||||
Cipher suites using MD5.
|
||||
|
||||
=item B<SHA1>, B<SHA>
|
||||
|
||||
Cipher suites using SHA1.
|
||||
|
||||
=item B<SHA256>, B<SHA384>
|
||||
|
||||
Cipher suites using SHA256 or SHA384.
|
||||
|
||||
=item B<aGOST>
|
||||
|
||||
Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication
|
||||
(needs an engine supporting GOST algorithms).
|
||||
|
||||
=item B<aGOST01>
|
||||
|
||||
Cipher suites using GOST R 34.10-2001 authentication.
|
||||
|
||||
=item B<kGOST>
|
||||
|
||||
Cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
|
||||
|
||||
=item B<GOST94>
|
||||
|
||||
Cipher suites, using HMAC based on GOST R 34.11-94.
|
||||
|
||||
=item B<GOST89MAC>
|
||||
|
||||
Cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
|
||||
|
||||
=item B<PSK>
|
||||
|
||||
All cipher suites using pre-shared keys (PSK).
|
||||
|
||||
=item B<kPSK>, B<kECDHEPSK>, B<kDHEPSK>, B<kRSAPSK>
|
||||
|
||||
Cipher suites using PSK key exchange, ECDHE_PSK, DHE_PSK or RSA_PSK.
|
||||
|
||||
=item B<aPSK>
|
||||
|
||||
Cipher suites using PSK authentication (currently all PSK modes apart from
|
||||
RSA_PSK).
|
||||
|
||||
=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
|
||||
|
||||
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 cipher suites
|
||||
(ECDHE-ECDSA-AES128-GCM-SHA256 and ECDHE-ECDSA-AES256-GCM-SHA384) are
|
||||
permissible.
|
||||
|
||||
=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,
|
||||
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
|
||||
|
||||
SSL_RSA_WITH_NULL_MD5 NULL-MD5
|
||||
SSL_RSA_WITH_NULL_SHA NULL-SHA
|
||||
SSL_RSA_WITH_RC4_128_MD5 RC4-MD5
|
||||
SSL_RSA_WITH_RC4_128_SHA RC4-SHA
|
||||
SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
|
||||
SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
|
||||
|
||||
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA
|
||||
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-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_WITH_RC4_128_MD5 ADH-RC4-MD5
|
||||
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
|
||||
|
||||
TLS_RSA_WITH_NULL_MD5 NULL-MD5
|
||||
TLS_RSA_WITH_NULL_SHA NULL-SHA
|
||||
TLS_RSA_WITH_RC4_128_MD5 RC4-MD5
|
||||
TLS_RSA_WITH_RC4_128_SHA RC4-SHA
|
||||
TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
|
||||
TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
|
||||
|
||||
TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
|
||||
TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
|
||||
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_WITH_RC4_128_MD5 ADH-RC4-MD5
|
||||
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
|
||||
|
||||
=head2 AES cipher suites from RFC3268, extending TLS v1.0
|
||||
|
||||
TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA
|
||||
TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA
|
||||
|
||||
TLS_DH_DSS_WITH_AES_128_CBC_SHA DH-DSS-AES128-SHA
|
||||
TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA
|
||||
TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA
|
||||
TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA
|
||||
|
||||
TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA
|
||||
TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA
|
||||
TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE-RSA-AES128-SHA
|
||||
TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA
|
||||
|
||||
TLS_DH_anon_WITH_AES_128_CBC_SHA ADH-AES128-SHA
|
||||
TLS_DH_anon_WITH_AES_256_CBC_SHA ADH-AES256-SHA
|
||||
|
||||
=head2 Camellia cipher suites from RFC4132, extending TLS v1.0
|
||||
|
||||
TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA
|
||||
TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA
|
||||
|
||||
TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA DH-DSS-CAMELLIA128-SHA
|
||||
TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA DH-DSS-CAMELLIA256-SHA
|
||||
TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA DH-RSA-CAMELLIA128-SHA
|
||||
TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA DH-RSA-CAMELLIA256-SHA
|
||||
|
||||
TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA
|
||||
TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA
|
||||
TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA DHE-RSA-CAMELLIA128-SHA
|
||||
TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA DHE-RSA-CAMELLIA256-SHA
|
||||
|
||||
TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA ADH-CAMELLIA128-SHA
|
||||
TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA ADH-CAMELLIA256-SHA
|
||||
|
||||
=head2 SEED cipher suites from RFC4162, extending TLS v1.0
|
||||
|
||||
TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA
|
||||
|
||||
TLS_DH_DSS_WITH_SEED_CBC_SHA DH-DSS-SEED-SHA
|
||||
TLS_DH_RSA_WITH_SEED_CBC_SHA DH-RSA-SEED-SHA
|
||||
|
||||
TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA
|
||||
TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA
|
||||
|
||||
TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA
|
||||
|
||||
=head2 GOST cipher suites from draft-chudov-cryptopro-cptls, extending TLS v1.0
|
||||
|
||||
Note: these ciphers require an engine which including GOST cryptographic
|
||||
algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
|
||||
|
||||
TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89
|
||||
TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89
|
||||
TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94
|
||||
TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94
|
||||
|
||||
=head2 Additional Export 1024 and other cipher suites
|
||||
|
||||
Note: these ciphers can also be used in SSL v3.
|
||||
|
||||
TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA
|
||||
|
||||
=head2 Elliptic curve cipher suites.
|
||||
|
||||
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
|
||||
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA
|
||||
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA
|
||||
|
||||
TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA
|
||||
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA
|
||||
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA
|
||||
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA
|
||||
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA
|
||||
|
||||
TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA
|
||||
TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA
|
||||
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA
|
||||
TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA
|
||||
TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA
|
||||
|
||||
=head2 TLS v1.2 cipher suites
|
||||
|
||||
TLS_RSA_WITH_NULL_SHA256 NULL-SHA256
|
||||
|
||||
TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256
|
||||
TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256
|
||||
TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256
|
||||
TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384
|
||||
|
||||
TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH-RSA-AES128-SHA256
|
||||
TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH-RSA-AES256-SHA256
|
||||
TLS_DH_RSA_WITH_AES_128_GCM_SHA256 DH-RSA-AES128-GCM-SHA256
|
||||
TLS_DH_RSA_WITH_AES_256_GCM_SHA384 DH-RSA-AES256-GCM-SHA384
|
||||
|
||||
TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH-DSS-AES128-SHA256
|
||||
TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH-DSS-AES256-SHA256
|
||||
TLS_DH_DSS_WITH_AES_128_GCM_SHA256 DH-DSS-AES128-GCM-SHA256
|
||||
TLS_DH_DSS_WITH_AES_256_GCM_SHA384 DH-DSS-AES256-GCM-SHA384
|
||||
|
||||
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE-RSA-AES128-SHA256
|
||||
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE-RSA-AES256-SHA256
|
||||
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE-RSA-AES128-GCM-SHA256
|
||||
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE-RSA-AES256-GCM-SHA384
|
||||
|
||||
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE-DSS-AES128-SHA256
|
||||
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE-DSS-AES256-SHA256
|
||||
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_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
|
||||
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384
|
||||
|
||||
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256
|
||||
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384
|
||||
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256
|
||||
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384
|
||||
|
||||
TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256
|
||||
TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256
|
||||
TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256
|
||||
TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384
|
||||
|
||||
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
|
||||
|
||||
=head2 ARIA cipher suites from RFC6209, extending TLS v1.2
|
||||
|
||||
Note: the CBC modes mentioned in this RFC are not supported.
|
||||
|
||||
TLS_RSA_WITH_ARIA_128_GCM_SHA256 ARIA128-GCM-SHA256
|
||||
TLS_RSA_WITH_ARIA_256_GCM_SHA384 ARIA256-GCM-SHA384
|
||||
TLS_DHE_RSA_WITH_ARIA_128_GCM_SHA256 DHE-RSA-ARIA128-GCM-SHA256
|
||||
TLS_DHE_RSA_WITH_ARIA_256_GCM_SHA384 DHE-RSA-ARIA256-GCM-SHA384
|
||||
TLS_DHE_DSS_WITH_ARIA_128_GCM_SHA256 DHE-DSS-ARIA128-GCM-SHA256
|
||||
TLS_DHE_DSS_WITH_ARIA_256_GCM_SHA384 DHE-DSS-ARIA256-GCM-SHA384
|
||||
TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256 ECDHE-ECDSA-ARIA128-GCM-SHA256
|
||||
TLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384 ECDHE-ECDSA-ARIA256-GCM-SHA384
|
||||
TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256 ECDHE-ARIA128-GCM-SHA256
|
||||
TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384 ECDHE-ARIA256-GCM-SHA384
|
||||
TLS_PSK_WITH_ARIA_128_GCM_SHA256 PSK-ARIA128-GCM-SHA256
|
||||
TLS_PSK_WITH_ARIA_256_GCM_SHA384 PSK-ARIA256-GCM-SHA384
|
||||
TLS_DHE_PSK_WITH_ARIA_128_GCM_SHA256 DHE-PSK-ARIA128-GCM-SHA256
|
||||
TLS_DHE_PSK_WITH_ARIA_256_GCM_SHA384 DHE-PSK-ARIA256-GCM-SHA384
|
||||
TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 RSA-PSK-ARIA128-GCM-SHA256
|
||||
TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 RSA-PSK-ARIA256-GCM-SHA384
|
||||
|
||||
=head2 Camellia HMAC-Based cipher suites from RFC6367, extending TLS v1.2
|
||||
|
||||
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
|
||||
|
||||
=head2 Pre-shared keying (PSK) cipher suites
|
||||
|
||||
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 TLS v1.3 cipher suites
|
||||
|
||||
TLS_AES_128_GCM_SHA256 TLS_AES_128_GCM_SHA256
|
||||
TLS_AES_256_GCM_SHA384 TLS_AES_256_GCM_SHA384
|
||||
TLS_CHACHA20_POLY1305_SHA256 TLS_CHACHA20_POLY1305_SHA256
|
||||
TLS_AES_128_CCM_SHA256 TLS_AES_128_CCM_SHA256
|
||||
TLS_AES_128_CCM_8_SHA256 TLS_AES_128_CCM_8_SHA256
|
||||
|
||||
=head2 Older names used by OpenSSL
|
||||
|
||||
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
|
||||
listed here because some ciphers were excluded at compile time.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Verbose listing of all OpenSSL ciphers including NULL ciphers:
|
||||
|
||||
openssl ciphers -v 'ALL:eNULL'
|
||||
|
||||
Include all ciphers except NULL and anonymous DH then sort by
|
||||
strength:
|
||||
|
||||
openssl ciphers -v 'ALL:!ADH:@STRENGTH'
|
||||
|
||||
Include all ciphers except ones with no encryption (eNULL) or no
|
||||
authentication (aNULL):
|
||||
|
||||
openssl ciphers -v 'ALL:!aNULL'
|
||||
|
||||
Include only 3DES ciphers and then place RSA ciphers last:
|
||||
|
||||
openssl ciphers -v '3DES:+RSA'
|
||||
|
||||
Include all RC4 ciphers but leave out those without authentication:
|
||||
|
||||
openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
|
||||
|
||||
Include all ciphers with RSA authentication but leave out ciphers without
|
||||
encryption.
|
||||
|
||||
openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
|
||||
|
||||
Set security level to 2 and display all ciphers consistent with level 2:
|
||||
|
||||
openssl ciphers -s -v 'ALL:@SECLEVEL=2'
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<s_client(1)>, L<s_server(1)>, L<ssl(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0.
|
||||
|
||||
The B<-stdname> is only available if OpenSSL is built with tracing enabled
|
||||
(B<enable-ssl-trace> argument to Configure) before OpenSSL 1.1.1.
|
||||
|
||||
The B<-convert> option was added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 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
|
||||
@@ -0,0 +1,745 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-cms,
|
||||
cms - CMS utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<cms>
|
||||
[B<-help>]
|
||||
[B<-encrypt>]
|
||||
[B<-decrypt>]
|
||||
[B<-sign>]
|
||||
[B<-verify>]
|
||||
[B<-cmsout>]
|
||||
[B<-resign>]
|
||||
[B<-data_create>]
|
||||
[B<-data_out>]
|
||||
[B<-digest_create>]
|
||||
[B<-digest_verify>]
|
||||
[B<-compress>]
|
||||
[B<-uncompress>]
|
||||
[B<-EncryptedData_encrypt>]
|
||||
[B<-sign_receipt>]
|
||||
[B<-verify_receipt receipt>]
|
||||
[B<-in filename>]
|
||||
[B<-inform SMIME|PEM|DER>]
|
||||
[B<-rctform SMIME|PEM|DER>]
|
||||
[B<-out filename>]
|
||||
[B<-outform SMIME|PEM|DER>]
|
||||
[B<-stream -indef -noindef>]
|
||||
[B<-noindef>]
|
||||
[B<-content filename>]
|
||||
[B<-text>]
|
||||
[B<-noout>]
|
||||
[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<-I<cipher>>]
|
||||
[B<-nointern>]
|
||||
[B<-noverify>]
|
||||
[B<-nocerts>]
|
||||
[B<-noattr>]
|
||||
[B<-nosmimecap>]
|
||||
[B<-binary>]
|
||||
[B<-crlfeol>]
|
||||
[B<-asciicrlf>]
|
||||
[B<-nodetach>]
|
||||
[B<-certfile file>]
|
||||
[B<-certsout file>]
|
||||
[B<-signer file>]
|
||||
[B<-recip file>]
|
||||
[B<-keyid>]
|
||||
[B<-receipt_request_all>]
|
||||
[B<-receipt_request_first>]
|
||||
[B<-receipt_request_from emailaddress>]
|
||||
[B<-receipt_request_to emailaddress>]
|
||||
[B<-receipt_request_print>]
|
||||
[B<-secretkey key>]
|
||||
[B<-secretkeyid id>]
|
||||
[B<-econtent_type type>]
|
||||
[B<-inkey file>]
|
||||
[B<-keyopt name:parameter>]
|
||||
[B<-passin arg>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<cert.pem...>]
|
||||
[B<-to addr>]
|
||||
[B<-from addr>]
|
||||
[B<-subject subj>]
|
||||
[cert.pem]...
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
|
||||
verify, compress and uncompress S/MIME messages.
|
||||
|
||||
=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
|
||||
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
|
||||
to be encrypted. The output file is the encrypted mail in MIME format. The
|
||||
actual CMS type is <B>EnvelopedData<B>.
|
||||
|
||||
Note that no revocation check is done for the recipient cert, so if that
|
||||
key has been compromised, others may be able to decrypt the text.
|
||||
|
||||
=item B<-decrypt>
|
||||
|
||||
Decrypt mail using the supplied certificate and private key. Expects an
|
||||
encrypted mail message in MIME format for the input file. The decrypted mail
|
||||
is written to the output file.
|
||||
|
||||
=item B<-debug_decrypt>
|
||||
|
||||
This option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used
|
||||
with caution: see the notes section below.
|
||||
|
||||
=item B<-sign>
|
||||
|
||||
Sign mail using the supplied certificate and private key. Input file is
|
||||
the message to be signed. The signed message in MIME format is written
|
||||
to the output file.
|
||||
|
||||
=item B<-verify>
|
||||
|
||||
Verify signed mail. Expects a signed mail message on input and outputs
|
||||
the signed data. Both clear text and opaque signing is supported.
|
||||
|
||||
=item B<-cmsout>
|
||||
|
||||
Takes an input message and writes out a PEM encoded CMS structure.
|
||||
|
||||
=item B<-resign>
|
||||
|
||||
Resign a message: take an existing message and one or more new signers.
|
||||
|
||||
=item B<-data_create>
|
||||
|
||||
Create a CMS B<Data> type.
|
||||
|
||||
=item B<-data_out>
|
||||
|
||||
B<Data> type and output the content.
|
||||
|
||||
=item B<-digest_create>
|
||||
|
||||
Create a CMS B<DigestedData> type.
|
||||
|
||||
=item B<-digest_verify>
|
||||
|
||||
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>
|
||||
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
|
||||
compiled with B<zlib> support for this option to work, otherwise it will
|
||||
output an error.
|
||||
|
||||
=item B<-EncryptedData_encrypt>
|
||||
|
||||
Encrypt content using supplied symmetric key and algorithm using a CMS
|
||||
B<EncryptedData> type and output the content.
|
||||
|
||||
=item B<-sign_receipt>
|
||||
|
||||
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>
|
||||
contain the original receipt request. Functionality is otherwise similar
|
||||
to the B<-verify> operation.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
The input message to be encrypted or signed or the message to be decrypted
|
||||
or verified.
|
||||
|
||||
=item B<-inform SMIME|PEM|DER>
|
||||
|
||||
This specifies the input format for the CMS structure. The default
|
||||
is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
|
||||
format change this to expect PEM and DER format CMS structures
|
||||
instead. This currently only affects the input format of the CMS
|
||||
structure, if no CMS structure is being input (for example with
|
||||
B<-encrypt> or B<-sign>) this option has no effect.
|
||||
|
||||
=item B<-rctform SMIME|PEM|DER>
|
||||
|
||||
Specify the format for a signed receipt for use with the B<-receipt_verify>
|
||||
operation.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
The message text that has been decrypted or verified or the output MIME
|
||||
format message that has been signed or verified.
|
||||
|
||||
=item B<-outform SMIME|PEM|DER>
|
||||
|
||||
This specifies the output format for the CMS structure. The default
|
||||
is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER>
|
||||
format change this to write PEM and DER format CMS structures
|
||||
instead. This currently only affects the output format of the CMS
|
||||
structure, if no CMS structure is being output (for example with
|
||||
B<-verify> or B<-decrypt>) this option has no effect.
|
||||
|
||||
=item B<-stream -indef -noindef>
|
||||
|
||||
The B<-stream> and B<-indef> options are equivalent and enable streaming I/O
|
||||
for encoding operations. This permits single pass processing of data without
|
||||
the need to hold the entire contents in memory, potentially supporting very
|
||||
large files. Streaming is automatically set for S/MIME signing with detached
|
||||
data if the output format is B<SMIME> it is currently off by default for all
|
||||
other operations.
|
||||
|
||||
=item B<-noindef>
|
||||
|
||||
Disable streaming I/O where it would produce and indefinite length constructed
|
||||
encoding. This option currently has no effect. In future streaming will be
|
||||
enabled by default on all relevant operations and this option will disable it.
|
||||
|
||||
=item B<-content filename>
|
||||
|
||||
This specifies a file containing the detached content, this is only
|
||||
useful with the B<-verify> command. This is only usable if the CMS
|
||||
structure is using the detached signature form where the content is
|
||||
not included. This option will override any content if the input format
|
||||
is S/MIME and it uses the multipart/signed MIME content type.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
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
|
||||
type text/plain then an error occurs.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
For the B<-cmsout> operation do not output the parsed CMS structure. This
|
||||
is useful when combined with the B<-print> option or if the syntax of the CMS
|
||||
structure is being checked.
|
||||
|
||||
=item B<-print>
|
||||
|
||||
For the B<-cmsout> operation print out all fields of the CMS structure. This
|
||||
is mainly useful for testing purposes.
|
||||
|
||||
=item B<-CAfile file>
|
||||
|
||||
A file containing trusted CA certificates, only used with B<-verify>.
|
||||
|
||||
=item B<-CApath dir>
|
||||
|
||||
A directory containing trusted CA certificates, only used with
|
||||
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
|
||||
default digest algorithm for the signing key will be used (usually SHA1).
|
||||
|
||||
=item B<-I<cipher>>
|
||||
|
||||
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<enc(1)> for a list of ciphers
|
||||
supported by your version of OpenSSL.
|
||||
|
||||
If not specified triple DES is used. Only used with B<-encrypt> and
|
||||
B<-EncryptedData_create> commands.
|
||||
|
||||
=item B<-nointern>
|
||||
|
||||
When verifying a message normally certificates (if any) included in
|
||||
the message are searched for the signing certificate. With this option
|
||||
only the certificates specified in the B<-certfile> option are used.
|
||||
The supplied certificates can still be used as untrusted CAs however.
|
||||
|
||||
=item B<-noverify>
|
||||
|
||||
Do not verify the signers certificate of a signed message.
|
||||
|
||||
=item B<-nocerts>
|
||||
|
||||
When signing a message the signer's certificate is normally included
|
||||
with this option it is excluded. This will reduce the size of the
|
||||
signed message but the verifier must have a copy of the signers certificate
|
||||
available locally (passed using the B<-certfile> option for example).
|
||||
|
||||
=item B<-noattr>
|
||||
|
||||
Normally when a message is signed a set of attributes are included which
|
||||
include the signing time and supported symmetric algorithms. With this
|
||||
option they are not included.
|
||||
|
||||
=item B<-nosmimecap>
|
||||
|
||||
Exclude the list of supported algorithms from signed attributes, other options
|
||||
such as signing time and content type are still included.
|
||||
|
||||
=item B<-binary>
|
||||
|
||||
Normally the input message is converted to "canonical" format which is
|
||||
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
|
||||
to translation by mail relays but it cannot be read by mail agents that
|
||||
do not support S/MIME. Without this option cleartext signing with
|
||||
the MIME type multipart/signed is used.
|
||||
|
||||
=item B<-certfile file>
|
||||
|
||||
Allows additional certificates to be specified. When signing these will
|
||||
be included with the message. When verifying these will be searched for
|
||||
the signers certificates. The certificates should be in PEM format.
|
||||
|
||||
=item B<-certsout file>
|
||||
|
||||
Any certificates contained in the message are written to B<file>.
|
||||
|
||||
=item B<-signer file>
|
||||
|
||||
A signing certificate when signing or resigning a message, this option can be
|
||||
used multiple times if more than one signer is required. If a message is being
|
||||
verified then the signers certificates will be written to this file if the
|
||||
verification was successful.
|
||||
|
||||
=item B<-recip file>
|
||||
|
||||
When decrypting a message this specifies the recipients certificate. The
|
||||
certificate must match one of the recipients of the message or an error
|
||||
occurs.
|
||||
|
||||
When encrypting a message this option may be used multiple times to specify
|
||||
each recipient. This form B<must> be used if customised parameters are
|
||||
required (for example to specify RSA-OAEP).
|
||||
|
||||
Only certificates carrying RSA, Diffie-Hellman or EC keys are supported by this
|
||||
option.
|
||||
|
||||
=item B<-keyid>
|
||||
|
||||
Use subject key identifier to identify certificates instead of issuer name and
|
||||
serial number. The supplied certificate B<must> include a subject key
|
||||
identifier extension. Supported by B<-sign> and B<-encrypt> options.
|
||||
|
||||
=item B<-receipt_request_all>, B<-receipt_request_first>
|
||||
|
||||
For B<-sign> option include a signed receipt request. Indicate requests should
|
||||
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>
|
||||
|
||||
For B<-sign> option include a signed receipt request. Add an explicit email
|
||||
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
|
||||
option B<must> but supplied if a signed receipt it requested.
|
||||
|
||||
=item B<-receipt_request_print>
|
||||
|
||||
For the B<-verify> operation print out the contents of any signed receipt
|
||||
requests.
|
||||
|
||||
=item B<-secretkey key>
|
||||
|
||||
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<-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.
|
||||
|
||||
=item B<-secretkeyid id>
|
||||
|
||||
The key identifier for the supplied symmetric key for B<KEKRecipientInfo> type.
|
||||
This option B<must> be present if the B<-secretkey> option is used with
|
||||
B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the
|
||||
relevant key if it is not supplied then an attempt is used to decrypt any
|
||||
B<KEKRecipientInfo> structures.
|
||||
|
||||
=item B<-econtent_type type>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-inkey file>
|
||||
|
||||
The private key to use when signing or decrypting. This must match the
|
||||
corresponding certificate. If this option is not specified then the
|
||||
private key must be included in the certificate file specified with
|
||||
the B<-recip> or B<-signer> file. When signing this option can be used
|
||||
multiple times to specify successive keys.
|
||||
|
||||
=item B<-keyopt name:opt>
|
||||
|
||||
For signing and encryption this option can be used multiple times to
|
||||
set customised parameters for the preceding key or certificate. It can
|
||||
currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
|
||||
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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<cert.pem...>
|
||||
|
||||
One or more certificates of message recipients: used when encrypting
|
||||
a message.
|
||||
|
||||
=item B<-to, -from, -subject>
|
||||
|
||||
The relevant mail headers. These are included outside the signed
|
||||
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<-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.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The MIME message must be sent without any blank lines between the
|
||||
headers and the output. Some mail programs will automatically add
|
||||
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 won't display it
|
||||
properly (if at all). You can use the B<-text> option to automatically
|
||||
add plain text headers.
|
||||
|
||||
A "signed and encrypted" message is one where a signed message is
|
||||
then encrypted. This can be produced by encrypting an already signed
|
||||
message: see the examples section.
|
||||
|
||||
This version of the program only allows one signer per message but it
|
||||
will verify multiple signers on received messages. Some S/MIME clients
|
||||
choke if a message contains multiple signers. It is possible to sign
|
||||
messages "in parallel" by signing an already signed message.
|
||||
|
||||
The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
|
||||
clients. Strictly speaking these process CMS enveloped data: CMS
|
||||
encrypted data is used for other purposes.
|
||||
|
||||
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 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.
|
||||
|
||||
Streaming is always used for the B<-sign> operation with detached data but
|
||||
since the content is no longer part of the CMS structure the encoding
|
||||
remains DER.
|
||||
|
||||
If the B<-decrypt> option is used without a recipient certificate then an
|
||||
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.
|
||||
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)>).
|
||||
|
||||
=head1 EXIT CODES
|
||||
|
||||
=over 4
|
||||
|
||||
=item Z<>0
|
||||
|
||||
The operation was completely successfully.
|
||||
|
||||
=item Z<>1
|
||||
|
||||
An error occurred parsing the command options.
|
||||
|
||||
=item Z<>2
|
||||
|
||||
One of the input files could not be read.
|
||||
|
||||
=item Z<>3
|
||||
|
||||
An error occurred creating the CMS file or when reading the MIME
|
||||
message.
|
||||
|
||||
=item Z<>4
|
||||
|
||||
An error occurred decrypting or verifying the message.
|
||||
|
||||
=item Z<>5
|
||||
|
||||
The message was verified correctly but an error occurred writing out
|
||||
the signers certificates.
|
||||
|
||||
=back
|
||||
|
||||
=head1 COMPATIBILITY WITH PKCS#7 format.
|
||||
|
||||
The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
|
||||
utility supports Cryptographic Message Syntax format. Use of some features
|
||||
will result in messages which cannot be processed by applications which only
|
||||
support the older format. These are detailed below.
|
||||
|
||||
The use of the B<-keyid> option with B<-sign> or B<-encrypt>.
|
||||
|
||||
The B<-outform PEM> option uses different headers.
|
||||
|
||||
The B<-compress> option.
|
||||
|
||||
The B<-secretkey> option when used with B<-encrypt>.
|
||||
|
||||
The use of PSS with B<-sign>.
|
||||
|
||||
The use of OAEP or non-RSA keys with B<-encrypt>.
|
||||
|
||||
Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
|
||||
be processed by the older B<smime> command.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Create a cleartext signed message:
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
Verify a message and extract the signer's certificate if successful:
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
The output from Netscape form signing is a PKCS#7 structure with the
|
||||
detached signature format. You can use this program to verify the
|
||||
signature by line wrapping the base64 encoded structure and surrounding
|
||||
it with:
|
||||
|
||||
-----BEGIN PKCS7-----
|
||||
-----END PKCS7-----
|
||||
|
||||
and using the command,
|
||||
|
||||
openssl 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
|
||||
|
||||
Create an encrypted message using 128 bit Camellia:
|
||||
|
||||
openssl 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
|
||||
|
||||
Sign mail using RSA-PSS:
|
||||
|
||||
openssl 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
|
||||
|
||||
Use SHA256 KDF with an ECDH certificate:
|
||||
|
||||
openssl cms -encrypt -in plain.txt -out mail.msg \
|
||||
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The MIME parser isn't very clever: it seems to handle most messages that I've
|
||||
thrown at it but it may choke on others.
|
||||
|
||||
The code currently will only write out the signer's certificate to a file: if
|
||||
the signer has a separate encryption certificate this must be manually
|
||||
extracted. There should be some heuristic that determines the correct
|
||||
encryption certificate.
|
||||
|
||||
Ideally a database should be maintained of a certificates for each email
|
||||
address.
|
||||
|
||||
The code doesn't currently take note of the permitted symmetric encryption
|
||||
algorithms as supplied in the SMIMECapabilities signed attribute. this means the
|
||||
user has to manually include the correct encryption algorithm. It should store
|
||||
the list of permitted ciphers in a database and only use those.
|
||||
|
||||
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.
|
||||
|
||||
The B<keyopt> option was added in OpenSSL 1.0.2.
|
||||
|
||||
Support for RSA-OAEP and RSA-PSS was added in OpenSSL 1.0.2.
|
||||
|
||||
The use of non-RSA keys with B<-encrypt> and B<-decrypt>
|
||||
was added in OpenSSL 1.0.2.
|
||||
|
||||
The -no_alt_chains option was added in OpenSSL 1.0.2b.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2008-2021 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
|
||||
@@ -0,0 +1,143 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-crl,
|
||||
crl - CRL utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<crl>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-text>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-nameopt option>]
|
||||
[B<-noout>]
|
||||
[B<-hash>]
|
||||
[B<-issuer>]
|
||||
[B<-lastupdate>]
|
||||
[B<-nextupdate>]
|
||||
[B<-CAfile file>]
|
||||
[B<-CApath dir>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<crl> command processes CRL files in DER or PEM format.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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.
|
||||
|
||||
=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)>.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
Don't output the encoded version of the CRL.
|
||||
|
||||
=item B<-hash>
|
||||
|
||||
Output a hash of the issuer name. This can be use to lookup CRLs in
|
||||
a directory by issuer name.
|
||||
|
||||
=item B<-hash_old>
|
||||
|
||||
Outputs the "hash" of the CRL issuer name using the older algorithm
|
||||
as used by OpenSSL before version 1.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>.
|
||||
|
||||
=item B<-CApath dir>
|
||||
|
||||
Verify the signature on a CRL by looking up the issuing certificate in
|
||||
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.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The PEM CRL format uses the header and footer lines:
|
||||
|
||||
-----BEGIN X509 CRL-----
|
||||
-----END X509 CRL-----
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Convert a CRL file from PEM to DER:
|
||||
|
||||
openssl crl -in crl.pem -outform DER -out crl.der
|
||||
|
||||
Output the text form of a DER encoded certificate:
|
||||
|
||||
openssl crl -in crl.der -inform DER -text -noout
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
Ideally it should be possible to create a CRL using appropriate options
|
||||
and files too.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<crl2pkcs7(1)>, L<ca(1)>, L<x509(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 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
|
||||
@@ -0,0 +1,106 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-crl2pkcs7,
|
||||
crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<crl2pkcs7>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-certfile filename>]
|
||||
[B<-nocrl>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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 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
|
||||
structure.B<PEM> (the default) is a base64 encoded version of
|
||||
the DER form with header and footer lines. The default format is PEM.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the PKCS#7 structure output format. B<DER> format is DER
|
||||
encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of
|
||||
the DER form with header and footer lines. The default format is PEM.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
This specifies the input filename to read a CRL from or standard input if this
|
||||
option is not specified.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
Specifies the output filename to write the PKCS#7 structure to or standard
|
||||
output by default.
|
||||
|
||||
=item B<-certfile filename>
|
||||
|
||||
Specifies a filename containing one or more certificates in B<PEM> format.
|
||||
All certificates in the file will be added to the PKCS#7 structure. This
|
||||
option can be used more than once to read certificates from multiple
|
||||
files.
|
||||
|
||||
=item B<-nocrl>
|
||||
|
||||
Normally a CRL is included in the output file. With this option no CRL is
|
||||
included in the output file and a CRL is not read from the input file.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Create a PKCS#7 structure from a certificate and CRL:
|
||||
|
||||
openssl 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
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The output file is a PKCS#7 signed data structure containing no signers and
|
||||
just certificates and an optional CRL.
|
||||
|
||||
This utility can be used to send certificates and CAs to Netscape as part of
|
||||
the certificate enrollment process. This involves sending the DER encoded output
|
||||
as MIME type application/x-x509-user-cert.
|
||||
|
||||
The B<PEM> encoded form with the header and footer lines removed can be used to
|
||||
install user certificates and CAs in MSIE using the Xenroll control.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<pkcs7(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,251 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-dgst,
|
||||
dgst - perform digest operations
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl dgst>
|
||||
[B<-I<digest>>]
|
||||
[B<-help>]
|
||||
[B<-c>]
|
||||
[B<-d>]
|
||||
[B<-list>]
|
||||
[B<-hex>]
|
||||
[B<-binary>]
|
||||
[B<-r>]
|
||||
[B<-out filename>]
|
||||
[B<-sign filename>]
|
||||
[B<-keyform arg>]
|
||||
[B<-passin arg>]
|
||||
[B<-verify filename>]
|
||||
[B<-prverify filename>]
|
||||
[B<-signature filename>]
|
||||
[B<-sigopt nm:v>]
|
||||
[B<-hmac key>]
|
||||
[B<-fips-fingerprint>]
|
||||
[B<-rand file...>]
|
||||
[B<-engine id>]
|
||||
[B<-engine_impl>]
|
||||
[B<file...>]
|
||||
|
||||
B<openssl> I<digest> [B<...>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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<sha256>.
|
||||
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.
|
||||
|
||||
=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>.
|
||||
|
||||
=item B<-c>
|
||||
|
||||
Print out the digest in two digit groups separated by colons, only relevant if
|
||||
B<hex> format output is used.
|
||||
|
||||
=item B<-d>
|
||||
|
||||
Print out BIO debugging information.
|
||||
|
||||
=item B<-list>
|
||||
|
||||
Prints out a list of supported message digests.
|
||||
|
||||
=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>.
|
||||
|
||||
=item B<-binary>
|
||||
|
||||
Output the digest or signature in binary form.
|
||||
|
||||
=item B<-r>
|
||||
|
||||
Output the digest in the "coreutils" format, including newlines.
|
||||
Used by programs like B<sha1sum>.
|
||||
|
||||
=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". Note this option
|
||||
does not support Ed25519 or Ed448 private keys.
|
||||
|
||||
=item B<-keyform arg>
|
||||
|
||||
Specifies the key format to sign digest with. The DER, PEM, P12,
|
||||
and ENGINE formats are supported.
|
||||
|
||||
=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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-verify filename>
|
||||
|
||||
Verify the signature using the public key in "filename".
|
||||
The output is either "Verification OK" or "Verification Failure".
|
||||
|
||||
=item B<-prverify filename>
|
||||
|
||||
Verify the signature using the private key in "filename".
|
||||
|
||||
=item B<-signature filename>
|
||||
|
||||
The actual signature to verify.
|
||||
|
||||
=item B<-hmac key>
|
||||
|
||||
Create a hashed MAC using "key".
|
||||
|
||||
=item B<-mac alg>
|
||||
|
||||
Create MAC (keyed Message Authentication Code). The most popular MAC
|
||||
algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
|
||||
which are not based on hash, for instance B<gost-mac> algorithm,
|
||||
supported by B<ccgost> engine. MAC keys and other options should be set
|
||||
via B<-macopt> parameter.
|
||||
|
||||
=item B<-macopt nm:v>
|
||||
|
||||
Passes options to MAC algorithm, specified by B<-mac> key.
|
||||
Following options are supported by both by B<HMAC> and B<gost-mac>:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<key:string>
|
||||
|
||||
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.
|
||||
|
||||
=item B<hexkey:string>
|
||||
|
||||
Specifies MAC key in hexadecimal form (two hex digits per byte).
|
||||
Key length must conform to any restrictions of the MAC algorithm
|
||||
for example exactly 32 chars for gost-mac.
|
||||
|
||||
=back
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-fips-fingerprint>
|
||||
|
||||
Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-engine_impl>
|
||||
|
||||
When used with the B<-engine> option, it specifies to also use
|
||||
engine B<id> for digest operations.
|
||||
|
||||
=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
|
||||
|
||||
To sign a file using SHA-256 with binary file output:
|
||||
openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt
|
||||
|
||||
To verify a signature:
|
||||
openssl dgst -sha256 -verify publickey.pem \
|
||||
-signature signature.sign \
|
||||
file.txt
|
||||
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The digest mechanisms that are available will depend on the options
|
||||
used when building OpenSSL.
|
||||
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.
|
||||
When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
|
||||
itself, not the related data to identify the signer and algorithm used in
|
||||
formats such as x.509, CMS, and S/MIME.
|
||||
|
||||
A source of random numbers is required for certain signing algorithms, in
|
||||
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"
|
||||
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 SHA256 in OpenSSL 1.1.0.
|
||||
The FIPS-related options were removed in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,166 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-dhparam,
|
||||
dhparam - DH parameter manipulation and generation
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl dhparam>
|
||||
[B<-help>]
|
||||
[B<-inform DER|PEM>]
|
||||
[B<-outform DER|PEM>]
|
||||
[B<-in> I<filename>]
|
||||
[B<-out> I<filename>]
|
||||
[B<-dsaparam>]
|
||||
[B<-check>]
|
||||
[B<-noout>]
|
||||
[B<-text>]
|
||||
[B<-C>]
|
||||
[B<-2>]
|
||||
[B<-5>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-engine id>]
|
||||
[I<numbits>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This command is used to manipulate DH parameter files.
|
||||
|
||||
=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
|
||||
form compatible with the PKCS#3 DHparameter structure. The 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>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=item B<-in> I<filename>
|
||||
|
||||
This specifies the input filename to read parameters from or standard input if
|
||||
this option is not specified.
|
||||
|
||||
=item B<-out> I<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<-dsaparam>
|
||||
|
||||
If this option is used, DSA rather than DH parameters are read or created;
|
||||
they are converted to DH format. Otherwise, "strong" primes (such
|
||||
that (p-1)/2 is also prime) will be used for DH parameter generation.
|
||||
|
||||
DH parameter generation with the B<-dsaparam> option is much faster,
|
||||
and the recommended exponent length is shorter, which makes DH key
|
||||
exchange more efficient. Beware that with such DSA-style DH
|
||||
parameters, a fresh DH key should be created for each use to
|
||||
avoid small-subgroup attacks that may be possible otherwise.
|
||||
|
||||
=item B<-check>
|
||||
|
||||
Performs numerous checks to see if the supplied parameters are valid and
|
||||
displays a warning if not.
|
||||
|
||||
=item B<-2>, B<-5>
|
||||
|
||||
The generator to use, either 2 or 5. If present then the
|
||||
input file is ignored and parameters are generated instead. If not
|
||||
present but B<numbits> is present, parameters are generated with the
|
||||
default generator 2.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item I<numbits>
|
||||
|
||||
This option specifies that a parameter set should be generated of size
|
||||
I<numbits>. It must be the last option. If this option is present then
|
||||
the input file is ignored and parameters are generated instead. If
|
||||
this option is not present but a generator (B<-2> or B<-5>) is
|
||||
present, parameters are generated with a default length of 2048 bits.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
This option inhibits the output of the encoded version of the parameters.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
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 get_dhNNNN() function.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<dhparam>
|
||||
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 WARNINGS
|
||||
|
||||
The program B<dhparam> combines the functionality of the programs B<dh> and
|
||||
B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh>
|
||||
programs are retained for now but may have different purposes in future
|
||||
versions of OpenSSL.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
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
|
||||
DH.
|
||||
|
||||
This program manipulates DH parameters not keys.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
There should be a way to generate and manipulate DH keys.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<dsaparam(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 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
|
||||
@@ -0,0 +1,182 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-dsa,
|
||||
dsa - DSA key processing
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<dsa>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-passin arg>]
|
||||
[B<-out filename>]
|
||||
[B<-passout arg>]
|
||||
[B<-aes128>]
|
||||
[B<-aes192>]
|
||||
[B<-aes256>]
|
||||
[B<-aria128>]
|
||||
[B<-aria192>]
|
||||
[B<-aria256>]
|
||||
[B<-camellia128>]
|
||||
[B<-camellia192>]
|
||||
[B<-camellia256>]
|
||||
[B<-des>]
|
||||
[B<-des3>]
|
||||
[B<-idea>]
|
||||
[B<-text>]
|
||||
[B<-noout>]
|
||||
[B<-modulus>]
|
||||
[B<-pubin>]
|
||||
[B<-pubout>]
|
||||
[B<-engine id>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<dsa> command processes DSA keys. They can be converted between various
|
||||
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 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
|
||||
an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of
|
||||
version (currently zero), p, q, g, the public and private key components
|
||||
respectively as ASN.1 INTEGERs. When used with a public key it uses a
|
||||
SubjectPublicKeyInfo structure: it is an error if the key is not DSA.
|
||||
|
||||
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.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write a key to or standard output by
|
||||
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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-aes128>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-idea>
|
||||
|
||||
These options encrypt the private key with the specified
|
||||
cipher 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<dsa> utility to read in an encrypted key with no
|
||||
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.
|
||||
|
||||
=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<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<dsa>
|
||||
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
|
||||
|
||||
The PEM private key format uses the header and footer lines:
|
||||
|
||||
-----BEGIN DSA PRIVATE KEY-----
|
||||
-----END DSA PRIVATE KEY-----
|
||||
|
||||
The PEM public key format uses the header and footer lines:
|
||||
|
||||
-----BEGIN PUBLIC KEY-----
|
||||
-----END PUBLIC KEY-----
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To remove the pass phrase on a DSA private key:
|
||||
|
||||
openssl dsa -in key.pem -out keyout.pem
|
||||
|
||||
To encrypt a private key using triple DES:
|
||||
|
||||
openssl dsa -in key.pem -des3 -out keyout.pem
|
||||
|
||||
To convert a private key from PEM to DER format:
|
||||
|
||||
openssl 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
|
||||
|
||||
To just output the public part of a private key:
|
||||
|
||||
openssl dsa -in key.pem -pubout -out pubkey.pem
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<dsaparam(1)>, L<gendsa(1)>, L<rsa(1)>,
|
||||
L<genrsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,131 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-dsaparam,
|
||||
dsaparam - DSA parameter manipulation and generation
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl dsaparam>
|
||||
[B<-help>]
|
||||
[B<-inform DER|PEM>]
|
||||
[B<-outform DER|PEM>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-noout>]
|
||||
[B<-text>]
|
||||
[B<-C>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-genkey>]
|
||||
[B<-engine id>]
|
||||
[B<numbits>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This command is used to manipulate or generate DSA parameter files.
|
||||
|
||||
=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
|
||||
form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting
|
||||
of p, q and g respectively. The 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>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
This specifies the input filename to read parameters from or standard input if
|
||||
this option is not specified. If the B<numbits> parameter is included then
|
||||
this option will be ignored.
|
||||
|
||||
=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 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 get_dsaXXX() function.
|
||||
|
||||
=item B<-genkey>
|
||||
|
||||
This option will generate a DSA either using the specified or generated
|
||||
parameters.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<numbits>
|
||||
|
||||
This option specifies that a parameter set should be generated of size
|
||||
B<numbits>. It must be the last option. If this option is included then
|
||||
the input file (if any) is ignored.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<dsaparam>
|
||||
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
|
||||
|
||||
PEM format DSA parameters use the header and footer lines:
|
||||
|
||||
-----BEGIN DSA PARAMETERS-----
|
||||
-----END DSA PARAMETERS-----
|
||||
|
||||
DSA parameter generation is a slow process and as a result the same set of
|
||||
DSA parameters is often used to generate several distinct keys.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<gendsa(1)>, L<dsa(1)>, L<genrsa(1)>,
|
||||
L<rsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 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
|
||||
@@ -0,0 +1,203 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-ec,
|
||||
ec - EC key processing
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<ec>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-passin arg>]
|
||||
[B<-out filename>]
|
||||
[B<-passout arg>]
|
||||
[B<-des>]
|
||||
[B<-des3>]
|
||||
[B<-idea>]
|
||||
[B<-text>]
|
||||
[B<-noout>]
|
||||
[B<-param_out>]
|
||||
[B<-pubin>]
|
||||
[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
|
||||
private key format specified in 'SEC 1: Elliptic Curve Cryptography'
|
||||
(http://www.secg.org/). To convert an OpenSSL EC private key into the
|
||||
PKCS#8 private key format use the B<pkcs8> command.
|
||||
|
||||
=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
|
||||
an ASN.1 DER encoded SEC1 private key. When used with a public key it
|
||||
uses the SubjectPublicKeyInfo structure as specified in RFC 3280.
|
||||
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.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write a key to or standard output by
|
||||
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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=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
|
||||
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
|
||||
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.
|
||||
|
||||
=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<-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
|
||||
into octet strings. Possible values are: B<compressed> (the default
|
||||
value), B<uncompressed> and B<hybrid>. For more information regarding
|
||||
the point conversion forms please read the X9.62 standard.
|
||||
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.
|
||||
|
||||
=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 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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<ec>
|
||||
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
|
||||
|
||||
The PEM private key format uses the header and footer lines:
|
||||
|
||||
-----BEGIN EC PRIVATE KEY-----
|
||||
-----END EC PRIVATE KEY-----
|
||||
|
||||
The PEM public key format uses the header and footer lines:
|
||||
|
||||
-----BEGIN PUBLIC KEY-----
|
||||
-----END PUBLIC KEY-----
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To encrypt a private key using triple DES:
|
||||
|
||||
openssl ec -in key.pem -des3 -out keyout.pem
|
||||
|
||||
To convert a private key from PEM to DER format:
|
||||
|
||||
openssl 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
|
||||
|
||||
To just output the public part of a private key:
|
||||
|
||||
openssl 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
|
||||
|
||||
To change the point conversion form to B<compressed>:
|
||||
|
||||
openssl ec -in key.pem -conv_form compressed -out keyout.pem
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ecparam(1)>, L<dsa(1)>, L<rsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2003-2021 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
|
||||
@@ -0,0 +1,192 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-ecparam,
|
||||
ecparam - EC parameter manipulation and generation
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl ecparam>
|
||||
[B<-help>]
|
||||
[B<-inform DER|PEM>]
|
||||
[B<-outform DER|PEM>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-noout>]
|
||||
[B<-text>]
|
||||
[B<-C>]
|
||||
[B<-check>]
|
||||
[B<-name arg>]
|
||||
[B<-list_curves>]
|
||||
[B<-conv_form arg>]
|
||||
[B<-param_enc arg>]
|
||||
[B<-no_seed>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-genkey>]
|
||||
[B<-engine id>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This command is used to manipulate or generate EC parameter files.
|
||||
|
||||
=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
|
||||
header and footer lines.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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 get_ec_group_XXX() function.
|
||||
|
||||
=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.
|
||||
|
||||
=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
|
||||
into octet strings. Possible values are: B<compressed>, B<uncompressed> (the
|
||||
default value) and B<hybrid>. For more information regarding
|
||||
the point conversion forms please read the X9.62 standard.
|
||||
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.
|
||||
|
||||
=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 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.
|
||||
|
||||
=item B<-no_seed>
|
||||
|
||||
This option inhibits that the 'seed' for the parameter generation
|
||||
is included in the ECParameters structure (see RFC 3279).
|
||||
|
||||
=item B<-genkey>
|
||||
|
||||
This option will generate an EC private key using the specified parameters.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<ecparam>
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To create EC parameters with the group 'prime192v1':
|
||||
|
||||
openssl 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
|
||||
|
||||
To validate given EC parameters:
|
||||
|
||||
openssl ecparam -in ec_param.pem -check
|
||||
|
||||
To create EC parameters and a private key:
|
||||
|
||||
openssl 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
|
||||
|
||||
To print out the EC parameters to standard output:
|
||||
|
||||
openssl ecparam -in ec_param.pem -noout -text
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ec(1)>, L<dsaparam(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2003-2018 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
|
||||
@@ -0,0 +1,438 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-enc,
|
||||
enc - symmetric cipher routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl enc -I<cipher>>
|
||||
[B<-help>]
|
||||
[B<-list>]
|
||||
[B<-ciphers>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-pass arg>]
|
||||
[B<-e>]
|
||||
[B<-d>]
|
||||
[B<-a>]
|
||||
[B<-base64>]
|
||||
[B<-A>]
|
||||
[B<-k password>]
|
||||
[B<-kfile filename>]
|
||||
[B<-K key>]
|
||||
[B<-iv IV>]
|
||||
[B<-S salt>]
|
||||
[B<-salt>]
|
||||
[B<-nosalt>]
|
||||
[B<-z>]
|
||||
[B<-md digest>]
|
||||
[B<-iter count>]
|
||||
[B<-pbkdf2>]
|
||||
[B<-p>]
|
||||
[B<-P>]
|
||||
[B<-bufsize number>]
|
||||
[B<-nopad>]
|
||||
[B<-debug>]
|
||||
[B<-none>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-engine id>]
|
||||
|
||||
B<openssl> I<[cipher]> [B<...>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The symmetric cipher commands allow data to be encrypted or decrypted
|
||||
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.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Print out a usage message.
|
||||
|
||||
=item B<-list>
|
||||
|
||||
List all supported ciphers.
|
||||
|
||||
=item B<-ciphers>
|
||||
|
||||
Alias of -list to display 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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-base64>
|
||||
|
||||
Same as B<-a>
|
||||
|
||||
=item B<-A>
|
||||
|
||||
If the B<-a> option is set then base64 process the data on one line.
|
||||
|
||||
=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.
|
||||
|
||||
=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
|
||||
the B<-pass> argument.
|
||||
|
||||
=item B<-md digest>
|
||||
|
||||
Use the specified digest to create the key from the passphrase.
|
||||
The default algorithm is sha-256.
|
||||
|
||||
=item B<-iter count>
|
||||
|
||||
Use a given number of iterations on the password in deriving the encryption key.
|
||||
High values increase the time required to brute-force the resulting file.
|
||||
This option enables the use of PBKDF2 algorithm to derive the key.
|
||||
|
||||
=item B<-pbkdf2>
|
||||
|
||||
Use PBKDF2 algorithm with default iteration count unless otherwise specified.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-salt>
|
||||
|
||||
Use salt (randomly generated or provide with B<-S> option) when
|
||||
encrypting, this is the default.
|
||||
|
||||
=item B<-S salt>
|
||||
|
||||
The actual salt to use: this must be represented as a string of hex digits.
|
||||
|
||||
=item B<-K key>
|
||||
|
||||
The actual key to use: this must be represented as a string comprised only
|
||||
of hex digits. If only the key is specified, the IV must additionally specified
|
||||
using the B<-iv> option. When both a key and a password are specified, the
|
||||
key given with the B<-K> option will be used and the IV generated from the
|
||||
password will be taken. It does not make much sense to specify both key
|
||||
and password.
|
||||
|
||||
=item B<-iv IV>
|
||||
|
||||
The actual IV to use: this must be represented as a string comprised only
|
||||
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.
|
||||
|
||||
=item B<-p>
|
||||
|
||||
Print out the key and IV used.
|
||||
|
||||
=item B<-P>
|
||||
|
||||
Print out the key and IV used then immediately exit: don't do any encryption
|
||||
or decryption.
|
||||
|
||||
=item B<-bufsize number>
|
||||
|
||||
Set the buffer size for I/O.
|
||||
|
||||
=item B<-nopad>
|
||||
|
||||
Disable standard block padding.
|
||||
|
||||
=item B<-debug>
|
||||
|
||||
Debug the BIOs used for I/O.
|
||||
|
||||
=item B<-z>
|
||||
|
||||
Compress or decompress clear text using zlib before encryption or after
|
||||
decryption. This option exists only if OpenSSL with compiled with zlib
|
||||
or zlib-dynamic option.
|
||||
|
||||
=item B<-none>
|
||||
|
||||
Use NULL cipher (no encryption or decryption of input).
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The program can be called either as B<openssl cipher> or
|
||||
B<openssl enc -cipher>. 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.
|
||||
Use the B<list> command to get a list of supported ciphers.
|
||||
|
||||
Engines which provide entirely new encryption algorithms (such as the ccgost
|
||||
engine which provides gost89 algorithm) should be configured in the
|
||||
configuration file. Engines specified on the command line using -engine
|
||||
options can only be used for hardware-assisted implementations of
|
||||
ciphers which are supported by the OpenSSL core or another engine specified
|
||||
in the configuration file.
|
||||
|
||||
When the enc command lists supported ciphers, ciphers provided by engines,
|
||||
specified in the configuration files are listed too.
|
||||
|
||||
A password will be prompted for to derive the key and IV if necessary.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
for this is that without the salt the same password always generates the same
|
||||
encryption key. When the salt is being used the first eight bytes of the
|
||||
encrypted data are reserved for the salt: it is generated at random when
|
||||
encrypting a file and read from the encrypted file when it is decrypted.
|
||||
|
||||
Some of the ciphers do not have large keys and others have security
|
||||
implications if not used correctly. A beginner is advised to just use
|
||||
a strong block cipher, such as AES, in CBC mode.
|
||||
|
||||
All the block ciphers normally use PKCS#5 padding, also known as standard
|
||||
block padding. This allows a rudimentary integrity or password check to
|
||||
be performed. However, since the chance of random data passing the test
|
||||
is better than 1 in 256 it isn't a very good test.
|
||||
|
||||
If padding is disabled then the input data must be a multiple of the cipher
|
||||
block length.
|
||||
|
||||
All RC2 ciphers have the same key and effective key length.
|
||||
|
||||
Blowfish and RC5 algorithms use a 128 bit key.
|
||||
|
||||
=head1 SUPPORTED CIPHERS
|
||||
|
||||
Note that some of these ciphers can be disabled at compile time
|
||||
and some are available only if an appropriate engine is configured
|
||||
in the configuration file. The output of the B<enc> command run with
|
||||
the B<-ciphers> option (that is B<openssl enc -ciphers>) produces a
|
||||
list of ciphers, supported by your version of OpenSSL, including
|
||||
ones provided by configured engines.
|
||||
|
||||
The B<enc> program does not support authenticated encryption modes
|
||||
like CCM and GCM, and will not support such modes in the future.
|
||||
The B<enc> interface by necessity must begin streaming output (e.g.,
|
||||
to standard output when B<-out> is not used) before the authentication
|
||||
tag could be validated, leading to the usage of B<enc> in pipelines
|
||||
that begin processing untrusted data and are not capable of rolling
|
||||
back upon authentication failure. The AEAD modes currently in common
|
||||
use also suffer from catastrophic failure of confidentiality and/or
|
||||
integrity upon reuse of key/iv/nonce, and since B<enc> places the
|
||||
entire burden of key/iv/nonce management upon the user, the risk of
|
||||
exposing AEAD modes is too great to allow. These key/iv/nonce
|
||||
management issues also affect other modes currently exposed in B<enc>,
|
||||
but the failure modes are less extreme in these cases, and the
|
||||
functionality cannot be removed with a stable release branch.
|
||||
For bulk encryption of data, whether using authenticated encryption
|
||||
modes or other modes, L<cms(1)> is recommended, as it provides a
|
||||
standard data format and performs the needed key/iv/nonce management.
|
||||
|
||||
|
||||
base64 Base 64
|
||||
|
||||
bf-cbc Blowfish in CBC mode
|
||||
bf Alias for bf-cbc
|
||||
blowfish Alias for bf-cbc
|
||||
bf-cfb Blowfish in CFB mode
|
||||
bf-ecb Blowfish in ECB mode
|
||||
bf-ofb Blowfish in OFB mode
|
||||
|
||||
cast-cbc CAST in CBC mode
|
||||
cast Alias for cast-cbc
|
||||
cast5-cbc CAST5 in CBC mode
|
||||
cast5-cfb CAST5 in CFB mode
|
||||
cast5-ecb CAST5 in ECB mode
|
||||
cast5-ofb CAST5 in OFB mode
|
||||
|
||||
chacha20 ChaCha20 algorithm
|
||||
|
||||
des-cbc DES in CBC mode
|
||||
des Alias for des-cbc
|
||||
des-cfb DES in CFB mode
|
||||
des-ofb DES in OFB mode
|
||||
des-ecb DES in ECB mode
|
||||
|
||||
des-ede-cbc Two key triple DES EDE in CBC mode
|
||||
des-ede Two key triple DES EDE in ECB mode
|
||||
des-ede-cfb Two key triple DES EDE in CFB mode
|
||||
des-ede-ofb Two key triple DES EDE in OFB mode
|
||||
|
||||
des-ede3-cbc Three key triple DES EDE in CBC mode
|
||||
des-ede3 Three key triple DES EDE in ECB mode
|
||||
des3 Alias for des-ede3-cbc
|
||||
des-ede3-cfb Three key triple DES EDE CFB mode
|
||||
des-ede3-ofb Three key triple DES EDE in OFB mode
|
||||
|
||||
desx DESX algorithm.
|
||||
|
||||
gost89 GOST 28147-89 in CFB mode (provided by ccgost engine)
|
||||
gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
|
||||
|
||||
idea-cbc IDEA algorithm in CBC mode
|
||||
idea same as idea-cbc
|
||||
idea-cfb IDEA in CFB mode
|
||||
idea-ecb IDEA in ECB mode
|
||||
idea-ofb IDEA in OFB mode
|
||||
|
||||
rc2-cbc 128 bit RC2 in CBC mode
|
||||
rc2 Alias for rc2-cbc
|
||||
rc2-cfb 128 bit RC2 in CFB mode
|
||||
rc2-ecb 128 bit RC2 in ECB mode
|
||||
rc2-ofb 128 bit RC2 in OFB mode
|
||||
rc2-64-cbc 64 bit RC2 in CBC mode
|
||||
rc2-40-cbc 40 bit RC2 in CBC mode
|
||||
|
||||
rc4 128 bit RC4
|
||||
rc4-64 64 bit RC4
|
||||
rc4-40 40 bit RC4
|
||||
|
||||
rc5-cbc RC5 cipher in CBC mode
|
||||
rc5 Alias for rc5-cbc
|
||||
rc5-cfb RC5 cipher in CFB mode
|
||||
rc5-ecb RC5 cipher in ECB mode
|
||||
rc5-ofb RC5 cipher in OFB mode
|
||||
|
||||
seed-cbc SEED cipher in CBC mode
|
||||
seed Alias for seed-cbc
|
||||
seed-cfb SEED cipher in CFB mode
|
||||
seed-ecb SEED cipher in ECB mode
|
||||
seed-ofb SEED cipher in OFB mode
|
||||
|
||||
sm4-cbc SM4 cipher in CBC mode
|
||||
sm4 Alias for sm4-cbc
|
||||
sm4-cfb SM4 cipher in CFB mode
|
||||
sm4-ctr SM4 cipher in CTR mode
|
||||
sm4-ecb SM4 cipher in ECB mode
|
||||
sm4-ofb SM4 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]-ctr 128/192/256 bit AES in CTR 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
|
||||
|
||||
aria-[128|192|256]-cbc 128/192/256 bit ARIA in CBC mode
|
||||
aria[128|192|256] Alias for aria-[128|192|256]-cbc
|
||||
aria-[128|192|256]-cfb 128/192/256 bit ARIA in 128 bit CFB mode
|
||||
aria-[128|192|256]-cfb1 128/192/256 bit ARIA in 1 bit CFB mode
|
||||
aria-[128|192|256]-cfb8 128/192/256 bit ARIA in 8 bit CFB mode
|
||||
aria-[128|192|256]-ctr 128/192/256 bit ARIA in CTR mode
|
||||
aria-[128|192|256]-ecb 128/192/256 bit ARIA in ECB mode
|
||||
aria-[128|192|256]-ofb 128/192/256 bit ARIA in OFB mode
|
||||
|
||||
camellia-[128|192|256]-cbc 128/192/256 bit Camellia in CBC mode
|
||||
camellia[128|192|256] Alias for camellia-[128|192|256]-cbc
|
||||
camellia-[128|192|256]-cfb 128/192/256 bit Camellia in 128 bit CFB mode
|
||||
camellia-[128|192|256]-cfb1 128/192/256 bit Camellia in 1 bit CFB mode
|
||||
camellia-[128|192|256]-cfb8 128/192/256 bit Camellia in 8 bit CFB mode
|
||||
camellia-[128|192|256]-ctr 128/192/256 bit Camellia in CTR mode
|
||||
camellia-[128|192|256]-ecb 128/192/256 bit Camellia in ECB mode
|
||||
camellia-[128|192|256]-ofb 128/192/256 bit Camellia in OFB mode
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Just base64 encode a binary file:
|
||||
|
||||
openssl base64 -in file.bin -out file.b64
|
||||
|
||||
Decode the same file
|
||||
|
||||
openssl base64 -d -in file.b64 -out file.bin
|
||||
|
||||
Encrypt a file using AES-128 using a prompted password
|
||||
and PBKDF2 key derivation:
|
||||
|
||||
openssl enc -aes128 -pbkdf2 -in file.txt -out file.aes128
|
||||
|
||||
Decrypt a file using a supplied password:
|
||||
|
||||
openssl enc -aes128 -pbkdf2 -d -in file.aes128 -out file.txt \
|
||||
-pass pass:<password>
|
||||
|
||||
Encrypt a file then base64 encode it (so it can be sent via mail for example)
|
||||
using AES-256 in CTR mode and PBKDF2 key derivation:
|
||||
|
||||
openssl enc -aes-256-ctr -pbkdf2 -a -in file.txt -out file.aes256
|
||||
|
||||
Base64 decode a file then decrypt it using a password supplied in a file:
|
||||
|
||||
openssl enc -aes-256-ctr -pbkdf2 -d -a -in file.aes256 -out file.txt \
|
||||
-pass file:<passfile>
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The B<-A> option when used with large files doesn't work properly.
|
||||
|
||||
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.0.
|
||||
|
||||
The B<-list> option was added in OpenSSL 1.1.1e.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,119 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-engine,
|
||||
engine - load and query engines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl engine>
|
||||
[ I<engine...> ]
|
||||
[B<-v>]
|
||||
[B<-vv>]
|
||||
[B<-vvv>]
|
||||
[B<-vvv>]
|
||||
[B<-vvv>]
|
||||
[B<-c>]
|
||||
[B<-t>]
|
||||
[B<-tt>]
|
||||
[B<-pre> I<command>]
|
||||
[B<-post> I<command>]
|
||||
[ I<engine...> ]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<engine> command is used to query the status and capabilities
|
||||
of the specified B<engine>'s.
|
||||
Engines may be specified before and after all other command-line flags.
|
||||
Only those specified are queried.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-v> B<-vv> B<-vvv> B<-vvvv>
|
||||
|
||||
Provides information about each specified engine. The first flag lists
|
||||
all the possible run-time control commands; the second adds a
|
||||
description of each command; the third adds the input flags, and the
|
||||
final option adds the internal input flags.
|
||||
|
||||
=item B<-c>
|
||||
|
||||
Lists the capabilities of each engine.
|
||||
|
||||
=item B<-t>
|
||||
|
||||
Tests if each specified engine is available, and displays the answer.
|
||||
|
||||
=item B<-tt>
|
||||
|
||||
Displays an error trace for any unavailable engine.
|
||||
|
||||
=item B<-pre> I<command>
|
||||
|
||||
=item B<-post> I<command>
|
||||
|
||||
Command-line configuration of engines.
|
||||
The B<-pre> command is given to the engine before it is loaded and
|
||||
the B<-post> command is given after the engine is loaded.
|
||||
The I<command> is of the form I<cmd:val> where I<cmd> is the command,
|
||||
and I<val> is the value for the command.
|
||||
See the example below.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To list all the commands available to a dynamic engine:
|
||||
|
||||
$ openssl engine -t -tt -vvvv dynamic
|
||||
(dynamic) Dynamic engine loading support
|
||||
[ unavailable ]
|
||||
SO_PATH: Specifies the path to the new ENGINE shared library
|
||||
(input flags): STRING
|
||||
NO_VCHECK: Specifies to continue even if version checking fails (boolean)
|
||||
(input flags): NUMERIC
|
||||
ID: Specifies an ENGINE id name for loading
|
||||
(input flags): STRING
|
||||
LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory)
|
||||
(input flags): NUMERIC
|
||||
DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory)
|
||||
(input flags): NUMERIC
|
||||
DIR_ADD: Adds a directory from which ENGINEs can be loaded
|
||||
(input flags): STRING
|
||||
LOAD: Load up the ENGINE specified by other settings
|
||||
(input flags): NO_INPUT
|
||||
|
||||
To list the capabilities of the I<rsax> engine:
|
||||
|
||||
$ openssl engine -c
|
||||
(rsax) RSAX engine support
|
||||
[RSA]
|
||||
(dynamic) Dynamic engine loading support
|
||||
|
||||
=head1 ENVIRONMENT
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<OPENSSL_ENGINES>
|
||||
|
||||
The path to the engines directory.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<config(5)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2019 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
|
||||
@@ -0,0 +1,46 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-errstr,
|
||||
errstr - lookup error codes
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl 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
|
||||
display the meaning of the hex code. The hex code is the hex digits after the
|
||||
second colon.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
None.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
The error code:
|
||||
|
||||
27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
|
||||
|
||||
can be displayed with:
|
||||
|
||||
openssl errstr 2006D080
|
||||
|
||||
to produce the error message:
|
||||
|
||||
error:2006D080:BIO routines:BIO_new_file:no such file
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2004-2019 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
|
||||
@@ -0,0 +1,101 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-gendsa,
|
||||
gendsa - generate a DSA private key from a set of parameters
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<gendsa>
|
||||
[B<-help>]
|
||||
[B<-out filename>]
|
||||
[B<-aes128>]
|
||||
[B<-aes192>]
|
||||
[B<-aes256>]
|
||||
[B<-aria128>]
|
||||
[B<-aria192>]
|
||||
[B<-aria256>]
|
||||
[B<-camellia128>]
|
||||
[B<-camellia192>]
|
||||
[B<-camellia256>]
|
||||
[B<-des>]
|
||||
[B<-des3>]
|
||||
[B<-idea>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-engine id>]
|
||||
[B<paramfile>]
|
||||
|
||||
=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).
|
||||
|
||||
=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>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-idea>
|
||||
|
||||
These options encrypt the private key with specified
|
||||
cipher before outputting it. A pass phrase is prompted for.
|
||||
If none of these options is specified no encryption is used.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<gendsa>
|
||||
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<paramfile>
|
||||
|
||||
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.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
DSA key generation is little more than random number generation so it is
|
||||
much quicker that RSA key generation for example.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<dsaparam(1)>, L<dsa(1)>, L<genrsa(1)>,
|
||||
L<rsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 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
|
||||
@@ -0,0 +1,335 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-genpkey,
|
||||
genpkey - generate a private key
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<genpkey>
|
||||
[B<-help>]
|
||||
[B<-out filename>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-pass arg>]
|
||||
[B<-I<cipher>>]
|
||||
[B<-engine id>]
|
||||
[B<-paramfile file>]
|
||||
[B<-algorithm alg>]
|
||||
[B<-pkeyopt opt:value>]
|
||||
[B<-genparam>]
|
||||
[B<-text>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<genpkey> command generates a private key.
|
||||
|
||||
=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<-outform DER|PEM>
|
||||
|
||||
This specifies the output format DER or PEM. The default format is PEM.
|
||||
|
||||
=item B<-pass arg>
|
||||
|
||||
The output file password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-I<cipher>>
|
||||
|
||||
This option encrypts the private key with the supplied cipher. Any algorithm
|
||||
name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<genpkey>
|
||||
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. If used this option should precede all other
|
||||
options.
|
||||
|
||||
=item B<-algorithm alg>
|
||||
|
||||
Public key algorithm to use such as RSA, DSA or DH. If used this option must
|
||||
precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
|
||||
are mutually exclusive. Engines may add algorithms in addition to the standard
|
||||
built-in ones.
|
||||
|
||||
Valid built-in algorithm names for private key generation are RSA, RSA-PSS, EC,
|
||||
X25519, X448, ED25519 and ED448.
|
||||
|
||||
Valid built-in algorithm names for parameter generation (see the B<-genparam>
|
||||
option) are DH, DSA and EC.
|
||||
|
||||
Note that the algorithm name X9.42 DH may be used as a synonym for the DH
|
||||
algorithm. These are identical and do not indicate the type of parameters that
|
||||
will be generated. Use the B<dh_paramgen_type> option to indicate whether PKCS#3
|
||||
or X9.42 DH parameters are required. See L<DH Parameter Generation Options>
|
||||
below for more details.
|
||||
|
||||
=item B<-pkeyopt opt:value>
|
||||
|
||||
Set the public key algorithm option B<opt> to B<value>. The precise set of
|
||||
options supported depends on the public key algorithm used and its
|
||||
implementation. See L<KEY GENERATION OPTIONS> and
|
||||
L<PARAMETER 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 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 any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
|
||||
are mutually exclusive.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
Print an (unencrypted) text representation of private and public keys and
|
||||
parameters along with the PEM or DER structure.
|
||||
|
||||
=back
|
||||
|
||||
=head1 KEY GENERATION OPTIONS
|
||||
|
||||
The options supported by each algorithm and indeed each implementation of an
|
||||
algorithm can vary. The options for the OpenSSL implementations are detailed
|
||||
below. There are no key generation options defined for the X25519, X448, ED25519
|
||||
or ED448 algorithms.
|
||||
|
||||
=head2 RSA Key Generation Options
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<rsa_keygen_bits:numbits>
|
||||
|
||||
The number of bits in the generated key. If not specified 2048 is used.
|
||||
|
||||
=item B<rsa_keygen_primes:numprimes>
|
||||
|
||||
The number of primes in the generated key. If not specified 2 is used.
|
||||
|
||||
=item B<rsa_keygen_pubexp:value>
|
||||
|
||||
The RSA public exponent value. This can be a large decimal or
|
||||
hexadecimal value if preceded by B<0x>. Default value is 65537.
|
||||
|
||||
=back
|
||||
|
||||
=head2 RSA-PSS Key Generation Options
|
||||
|
||||
Note: by default an B<RSA-PSS> key has no parameter restrictions.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<rsa_keygen_bits:numbits>, B<rsa_keygen_primes:numprimes>, B<rsa_keygen_pubexp:value>
|
||||
|
||||
These options have the same meaning as the B<RSA> algorithm.
|
||||
|
||||
=item B<rsa_pss_keygen_md:digest>
|
||||
|
||||
If set the key is restricted and can only use B<digest> for signing.
|
||||
|
||||
=item B<rsa_pss_keygen_mgf1_md:digest>
|
||||
|
||||
If set the key is restricted and can only use B<digest> as it's MGF1
|
||||
parameter.
|
||||
|
||||
=item B<rsa_pss_keygen_saltlen:len>
|
||||
|
||||
If set the key is restricted and B<len> specifies the minimum salt length.
|
||||
|
||||
=back
|
||||
|
||||
=head2 EC Key Generation Options
|
||||
|
||||
The EC key generation options can also be used for parameter generation.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<ec_paramgen_curve:curve>
|
||||
|
||||
The EC curve to use. OpenSSL 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". The default value is "named_curve".
|
||||
|
||||
=back
|
||||
|
||||
=head1 PARAMETER GENERATION OPTIONS
|
||||
|
||||
The options supported by each algorithm and indeed each implementation of an
|
||||
algorithm can vary. The options for the OpenSSL implementations are detailed
|
||||
below.
|
||||
|
||||
=head2 DSA Parameter Generation Options
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<dsa_paramgen_bits:numbits>
|
||||
|
||||
The number of bits in the generated prime. If not specified 2048 is used.
|
||||
|
||||
=item B<dsa_paramgen_q_bits:numbits>
|
||||
|
||||
The number of bits in the q parameter. Must be one of 160, 224 or 256. If not
|
||||
specified 224 is used.
|
||||
|
||||
=item B<dsa_paramgen_md:digest>
|
||||
|
||||
The digest to use during parameter generation. Must be one of B<sha1>, B<sha224>
|
||||
or B<sha256>. If set, then the number of bits in B<q> will match the output size
|
||||
of the specified digest and the B<dsa_paramgen_q_bits> parameter will be
|
||||
ignored. If not set, then a digest will be used that gives an output matching
|
||||
the number of bits in B<q>, i.e. B<sha1> if q length is 160, B<sha224> if it 224
|
||||
or B<sha256> if it is 256.
|
||||
|
||||
=back
|
||||
|
||||
=head2 DH Parameter Generation Options
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<dh_paramgen_prime_len:numbits>
|
||||
|
||||
The number of bits in the prime parameter B<p>. The default is 2048.
|
||||
|
||||
=item B<dh_paramgen_subprime_len:numbits>
|
||||
|
||||
The number of bits in the sub prime parameter B<q>. The default is 256 if the
|
||||
prime is at least 2048 bits long or 160 otherwise. Only relevant if used in
|
||||
conjunction with the B<dh_paramgen_type> option to generate X9.42 DH parameters.
|
||||
|
||||
=item B<dh_paramgen_generator:value>
|
||||
|
||||
The value to use for the generator B<g>. The default is 2.
|
||||
|
||||
=item B<dh_paramgen_type:value>
|
||||
|
||||
The type of DH parameters to generate. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
|
||||
The default is 0.
|
||||
|
||||
=item B<dh_rfc5114:num>
|
||||
|
||||
If this option is set, then the appropriate RFC5114 parameters are used
|
||||
instead of generating new parameters. The value B<num> can take the
|
||||
values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of
|
||||
1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup
|
||||
and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
|
||||
2.1, 2.2 and 2.3 respectively. If present this overrides all other DH parameter
|
||||
options.
|
||||
|
||||
=back
|
||||
|
||||
=head2 EC Parameter Generation Options
|
||||
|
||||
The EC parameter generation options are the same as for key generation. See
|
||||
L<EC Key Generation Options> above.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The use of the genpkey program is encouraged over the algorithm specific
|
||||
utilities because additional algorithm options and ENGINE provided algorithms
|
||||
can be used.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Generate an RSA private key using default parameters:
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
Generate 2048 bit DSA parameters:
|
||||
|
||||
openssl genpkey -genparam -algorithm DSA -out dsap.pem \
|
||||
-pkeyopt dsa_paramgen_bits:2048
|
||||
|
||||
Generate DSA key from parameters:
|
||||
|
||||
openssl genpkey -paramfile dsap.pem -out dsakey.pem
|
||||
|
||||
Generate 2048 bit DH parameters:
|
||||
|
||||
openssl genpkey -genparam -algorithm DH -out dhp.pem \
|
||||
-pkeyopt dh_paramgen_prime_len:2048
|
||||
|
||||
Generate 2048 bit X9.42 DH parameters:
|
||||
|
||||
openssl genpkey -genparam -algorithm DH -out dhpx.pem \
|
||||
-pkeyopt dh_paramgen_prime_len:2048 \
|
||||
-pkeyopt dh_paramgen_type:1
|
||||
|
||||
Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
|
||||
|
||||
openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
|
||||
|
||||
Generate DH key from parameters:
|
||||
|
||||
openssl genpkey -paramfile dhp.pem -out dhkey.pem
|
||||
|
||||
Generate EC parameters:
|
||||
|
||||
openssl genpkey -genparam -algorithm EC -out ecp.pem \
|
||||
-pkeyopt ec_paramgen_curve:secp384r1 \
|
||||
-pkeyopt ec_param_enc:named_curve
|
||||
|
||||
Generate EC key from parameters:
|
||||
|
||||
openssl genpkey -paramfile ecp.pem -out eckey.pem
|
||||
|
||||
Generate EC key directly:
|
||||
|
||||
openssl genpkey -algorithm EC -out eckey.pem \
|
||||
-pkeyopt ec_paramgen_curve:P-384 \
|
||||
-pkeyopt ec_param_enc:named_curve
|
||||
|
||||
Generate an X25519 private key:
|
||||
|
||||
openssl genpkey -algorithm X25519 -out xkey.pem
|
||||
|
||||
Generate an ED448 private key:
|
||||
|
||||
openssl genpkey -algorithm ED448 -out xkey.pem
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The ability to use NIST curve names, and to generate an EC key directly,
|
||||
were added in OpenSSL 1.0.2.
|
||||
The ability to generate X25519 keys was added in OpenSSL 1.1.0.
|
||||
The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2006-2021 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
|
||||
@@ -0,0 +1,128 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-genrsa,
|
||||
genrsa - generate an RSA private key
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> 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>]
|
||||
[B<-des>]
|
||||
[B<-des3>]
|
||||
[B<-idea>]
|
||||
[B<-f4>]
|
||||
[B<-3>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-engine id>]
|
||||
[B<-primes num>]
|
||||
[B<numbits>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<genrsa> command generates an RSA private key.
|
||||
|
||||
=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<-passout arg>
|
||||
|
||||
The output file password source. For more information about the format
|
||||
of B<arg> see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-aes128>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-idea>
|
||||
|
||||
These options encrypt the private key with specified
|
||||
cipher before outputting it. If none of these options is
|
||||
specified no encryption is used. If encryption is used a pass phrase is prompted
|
||||
for if it is not supplied via the B<-passout> argument.
|
||||
|
||||
=item B<-F4|-3>
|
||||
|
||||
The public exponent to use, either 65537 or 3. The default is 65537.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<genrsa>
|
||||
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<-primes num>
|
||||
|
||||
Specify the number of primes to use while generating the RSA key. The B<num>
|
||||
parameter must be a positive integer that is greater than 1 and less than 16.
|
||||
If B<num> is greater than 2, then the generated key is called a 'multi-prime'
|
||||
RSA key, which is defined in RFC 8017.
|
||||
|
||||
=item B<numbits>
|
||||
|
||||
The size of the private key to generate in bits. This must be the last option
|
||||
specified. The default is 2048 and values less than 512 are not allowed.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
RSA private key generation essentially involves the generation of two or more
|
||||
prime numbers. When generating a private key various symbols will be output to
|
||||
indicate the progress of the generation. A B<.> represents each number which
|
||||
has passed an initial sieve test, B<+> means a number has passed a single
|
||||
round of the Miller-Rabin primality test, B<*> means the current prime starts
|
||||
a regenerating progress due to some failed tests. A newline means that the number
|
||||
has passed all the prime tests (the actual number depends on the key size).
|
||||
|
||||
Because key generation is a random process the time taken to generate a key
|
||||
may vary somewhat. But in general, more primes lead to less generation time
|
||||
of a key.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<gendsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,94 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-list,
|
||||
list - list algorithms and features
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl list>
|
||||
[B<-help>]
|
||||
[B<-1>]
|
||||
[B<-commands>]
|
||||
[B<-digest-commands>]
|
||||
[B<-digest-algorithms>]
|
||||
[B<-cipher-commands>]
|
||||
[B<-cipher-algorithms>]
|
||||
[B<-public-key-algorithms>]
|
||||
[B<-public-key-methods>]
|
||||
[B<-disabled>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This command is used to generate list of algorithms or disabled
|
||||
features.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Display a usage message.
|
||||
|
||||
=item B<-1>
|
||||
|
||||
List the commands, digest-commands, or cipher-commands in a single column.
|
||||
If used, this option must be given first.
|
||||
|
||||
=item B<-commands>
|
||||
|
||||
Display a list of standard commands.
|
||||
|
||||
=item B<-digest-commands>
|
||||
|
||||
Display a list of message digest commands, which are typically used
|
||||
as input to the L<dgst(1)> or L<speed(1)> commands.
|
||||
|
||||
=item B<-digest-algorithms>
|
||||
|
||||
Display a list of message digest algorithms.
|
||||
If a line is of the form
|
||||
foo => bar
|
||||
then B<foo> is an alias for the official algorithm name, B<bar>.
|
||||
|
||||
=item B<-cipher-commands>
|
||||
|
||||
Display a list of cipher commands, which are typically used as input
|
||||
to the L<dgst(1)> or L<speed(1)> commands.
|
||||
|
||||
=item B<-cipher-algorithms>
|
||||
|
||||
Display a list of cipher algorithms.
|
||||
If a line is of the form
|
||||
foo => bar
|
||||
then B<foo> is an alias for the official algorithm name, B<bar>.
|
||||
|
||||
=item B<-public-key-algorithms>
|
||||
|
||||
Display a list of public key algorithms, with each algorithm as
|
||||
a block of multiple lines, all but the first are indented.
|
||||
|
||||
=item B<-public-key-methods>
|
||||
|
||||
Display a list of public key method OIDs: this also includes public key methods
|
||||
without an associated ASN.1 method, for example, KDF algorithms.
|
||||
|
||||
=item B<-disabled>
|
||||
|
||||
Display a list of disabled features, those that were compiled out
|
||||
of the installation.
|
||||
|
||||
=back
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2017 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
|
||||
@@ -0,0 +1,85 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-nseq,
|
||||
nseq - create or examine a Netscape certificate sequence
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<nseq>
|
||||
[B<-help>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-toseq>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<nseq> command takes a file containing a Netscape certificate
|
||||
sequence and prints out the certificates contained in it or takes a
|
||||
file of certificates and converts it into a Netscape certificate
|
||||
sequence.
|
||||
|
||||
=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
|
||||
option is not specified.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
Specifies the output filename or standard output by default.
|
||||
|
||||
=item B<-toseq>
|
||||
|
||||
Normally a Netscape certificate sequence will be input and the output
|
||||
is the certificates contained in it. With the B<-toseq> option the
|
||||
situation is reversed: a Netscape certificate sequence is created from
|
||||
a file of certificates.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Output the certificates in a Netscape certificate sequence
|
||||
|
||||
openssl nseq -in nseq.pem -out certs.pem
|
||||
|
||||
Create a Netscape certificate sequence
|
||||
|
||||
openssl nseq -in certs.pem -toseq -out nseq.pem
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The B<PEM> encoded form uses the same headers and footers as a certificate:
|
||||
|
||||
-----BEGIN CERTIFICATE-----
|
||||
-----END CERTIFICATE-----
|
||||
|
||||
A Netscape certificate sequence is a Netscape specific format that can be sent
|
||||
to browsers as an alternative to the standard PKCS#7 format when several
|
||||
certificates are sent to the browser: for example during certificate enrollment.
|
||||
It is used by Netscape certificate server for example.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
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-2017 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
|
||||
@@ -0,0 +1,500 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-ocsp,
|
||||
ocsp - Online Certificate Status Protocol utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<ocsp>
|
||||
[B<-help>]
|
||||
[B<-out file>]
|
||||
[B<-issuer file>]
|
||||
[B<-cert file>]
|
||||
[B<-serial n>]
|
||||
[B<-signer file>]
|
||||
[B<-signkey file>]
|
||||
[B<-sign_other file>]
|
||||
[B<-no_certs>]
|
||||
[B<-req_text>]
|
||||
[B<-resp_text>]
|
||||
[B<-text>]
|
||||
[B<-reqout file>]
|
||||
[B<-respout file>]
|
||||
[B<-reqin file>]
|
||||
[B<-respin file>]
|
||||
[B<-nonce>]
|
||||
[B<-no_nonce>]
|
||||
[B<-url URL>]
|
||||
[B<-host host:port>]
|
||||
[B<-multi process-count>]
|
||||
[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>]
|
||||
[B<-noverify>]
|
||||
[B<-verify_other file>]
|
||||
[B<-trust_other>]
|
||||
[B<-no_intern>]
|
||||
[B<-no_signature_verify>]
|
||||
[B<-no_cert_verify>]
|
||||
[B<-no_chain>]
|
||||
[B<-no_cert_checks>]
|
||||
[B<-no_explicit>]
|
||||
[B<-port num>]
|
||||
[B<-ignore_err>]
|
||||
[B<-index file>]
|
||||
[B<-CA file>]
|
||||
[B<-rsigner file>]
|
||||
[B<-rkey file>]
|
||||
[B<-rother file>]
|
||||
[B<-rsigopt nm:v>]
|
||||
[B<-resp_no_certs>]
|
||||
[B<-nmin n>]
|
||||
[B<-ndays n>]
|
||||
[B<-resp_key_id>]
|
||||
[B<-nrequest n>]
|
||||
[B<-I<digest>>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The Online Certificate Status Protocol (OCSP) enables applications to
|
||||
determine the (revocation) state of an identified certificate (RFC 2560).
|
||||
|
||||
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 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.
|
||||
|
||||
=item B<-issuer filename>
|
||||
|
||||
This specifies the current issuer certificate. This option can be used
|
||||
multiple times. The certificate specified in B<filename> must be in
|
||||
PEM format. This option B<MUST> come before any B<-cert> options.
|
||||
|
||||
=item B<-cert filename>
|
||||
|
||||
Add the certificate B<filename> to the request. The issuer certificate
|
||||
is taken from the previous B<issuer> option, or an error occurs if no
|
||||
issuer certificate is specified.
|
||||
|
||||
=item B<-serial num>
|
||||
|
||||
Same as the B<cert> option except the certificate with serial number
|
||||
B<num> is added to the request. The serial number is interpreted as a
|
||||
decimal integer unless preceded by B<0x>. Negative integers can also
|
||||
be specified by preceding the value by a B<-> sign.
|
||||
|
||||
=item B<-signer filename>, B<-signkey filename>
|
||||
|
||||
Sign the OCSP request using the certificate specified in the B<signer>
|
||||
option and the private key specified by the B<signkey> option. If
|
||||
the B<signkey> option is not present then the private key is read
|
||||
from the same file as the certificate. If neither option is specified then
|
||||
the OCSP request is not signed.
|
||||
|
||||
=item B<-sign_other filename>
|
||||
|
||||
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<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.
|
||||
|
||||
=item B<-req_text>, B<-resp_text>, B<-text>
|
||||
|
||||
Print out the text form of the OCSP request, response or both respectively.
|
||||
|
||||
=item B<-reqout file>, B<-respout file>
|
||||
|
||||
Write out the DER encoded certificate request or response to B<file>.
|
||||
|
||||
=item B<-reqin file>, B<-respin file>
|
||||
|
||||
Read OCSP request or response file from B<file>. These option are ignored
|
||||
if OCSP request or response creation is implied by other options (for example
|
||||
with B<serial>, B<cert> and B<host> options).
|
||||
|
||||
=item B<-url responder_url>
|
||||
|
||||
Specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
|
||||
|
||||
=item B<-host hostname:port>, B<-path pathname>
|
||||
|
||||
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 pathname to use
|
||||
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>
|
||||
|
||||
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>
|
||||
|
||||
Connection timeout to the OCSP responder in seconds.
|
||||
On POSIX systems, when running as an OCSP responder, this option also limits
|
||||
the time that the responder is willing to wait for the client request.
|
||||
This time is measured from the time the responder accepts the connection until
|
||||
the complete request is received.
|
||||
|
||||
=item B<-multi process-count>
|
||||
|
||||
Run the specified number of OCSP responder child processes, with the parent
|
||||
process respawning child processes as needed.
|
||||
Child processes will detect changes in the CA index file and automatically
|
||||
reload it.
|
||||
When running as a responder B<-timeout> option is recommended to limit the time
|
||||
each child is willing to wait for the client's OCSP response.
|
||||
This option is available on POSIX systems (that support the fork() and other
|
||||
required unix system-calls).
|
||||
|
||||
=item B<-CAfile file>, B<-CApath pathname>
|
||||
|
||||
File or pathname containing trusted CA certificates. These are used to verify
|
||||
the signature on the OCSP response.
|
||||
|
||||
=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<-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>
|
||||
|
||||
File containing additional certificates to search when attempting to locate
|
||||
the OCSP response signing certificate. Some responders omit the actual signer's
|
||||
certificate from the response: this option can be used to supply the necessary
|
||||
certificate in such cases.
|
||||
|
||||
=item B<-trust_other>
|
||||
|
||||
The certificates specified by the B<-verify_other> option should be explicitly
|
||||
trusted and no additional checks will be performed on them. This is useful
|
||||
when the complete responder certificate chain is not available or trusting a
|
||||
root CA is not appropriate.
|
||||
|
||||
=item B<-VAfile file>
|
||||
|
||||
File containing explicitly trusted responder certificates. Equivalent to the
|
||||
B<-verify_other> and B<-trust_other> options.
|
||||
|
||||
=item B<-noverify>
|
||||
|
||||
Don't attempt to verify the OCSP response signature or the nonce
|
||||
values. This option will normally only be used for debugging since it
|
||||
disables all verification of the responders certificate.
|
||||
|
||||
=item B<-no_intern>
|
||||
|
||||
Ignore certificates contained in the OCSP response when searching for the
|
||||
signers certificate. With this option the signers certificate must be specified
|
||||
with either the B<-verify_other> or B<-VAfile> options.
|
||||
|
||||
=item B<-no_signature_verify>
|
||||
|
||||
Don't check the signature on the OCSP response. Since this option
|
||||
tolerates invalid signatures on OCSP responses it will normally only be
|
||||
used for testing purposes.
|
||||
|
||||
=item B<-no_cert_verify>
|
||||
|
||||
Don't verify the OCSP response signers certificate at all. Since this
|
||||
option allows the OCSP response to be signed by any certificate it should
|
||||
only be used for testing purposes.
|
||||
|
||||
=item B<-no_chain>
|
||||
|
||||
Do not use certificates in the response as additional untrusted CA
|
||||
certificates.
|
||||
|
||||
=item B<-no_explicit>
|
||||
|
||||
Do not explicitly trust the root CA if it is set to be trusted for OCSP signing.
|
||||
|
||||
=item B<-no_cert_checks>
|
||||
|
||||
Don't perform any additional checks on the OCSP response signers certificate.
|
||||
That is do not make any checks to see if the signers certificate is authorised
|
||||
to provide the necessary status information: as a result this option should
|
||||
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.
|
||||
|
||||
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<-I<digest>>
|
||||
|
||||
This option sets digest algorithm to use for certificate identification in the
|
||||
OCSP request. Any digest supported by the OpenSSL 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
|
||||
|
||||
=head2 OCSP Server Options
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-index indexfile>
|
||||
|
||||
The B<indexfile> parameter is the name of a text index file in B<ca>
|
||||
format containing certificate revocation 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<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.
|
||||
|
||||
=item B<-CA file>
|
||||
|
||||
CA certificate corresponding to the revocation information in B<indexfile>.
|
||||
|
||||
=item B<-rsigner file>
|
||||
|
||||
The certificate to sign OCSP responses with.
|
||||
|
||||
=item B<-rother file>
|
||||
|
||||
Additional certificates to include in the OCSP response.
|
||||
|
||||
=item B<-resp_no_certs>
|
||||
|
||||
Don't include any certificates in the OCSP response.
|
||||
|
||||
=item B<-resp_key_id>
|
||||
|
||||
Identify the signer certificate using the key ID, default is to use the
|
||||
subject name.
|
||||
|
||||
=item B<-rkey file>
|
||||
|
||||
The private key to sign OCSP responses with: if not present the file
|
||||
specified in the B<rsigner> option is used.
|
||||
|
||||
=item B<-rsigopt nm:v>
|
||||
|
||||
Pass options to the signature algorithm when signing OCSP responses.
|
||||
Names and values of these options are algorithm-specific.
|
||||
|
||||
=item B<-port portnum>
|
||||
|
||||
Port to listen for OCSP requests on. The port may also be specified
|
||||
using the B<url> option.
|
||||
|
||||
=item B<-ignore_err>
|
||||
|
||||
Ignore malformed requests or responses: When acting as an OCSP client, retry if
|
||||
a malformed response is received. When acting as an OCSP responder, continue
|
||||
running instead of terminating upon receiving a malformed request.
|
||||
|
||||
=item B<-nrequest number>
|
||||
|
||||
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.
|
||||
|
||||
=back
|
||||
|
||||
=head1 OCSP Response verification.
|
||||
|
||||
OCSP Response follows the rules specified in RFC2560.
|
||||
|
||||
Initially the OCSP responder certificate is located and the signature on
|
||||
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
|
||||
certificates directory.
|
||||
|
||||
If the initial verify fails then the OCSP verify process halts with an
|
||||
error.
|
||||
|
||||
Otherwise the issuing CA certificate in the request is compared to the OCSP
|
||||
responder certificate: if there is a match then the OCSP verify succeeds.
|
||||
|
||||
Otherwise the OCSP responder certificate's CA is checked against the issuing
|
||||
CA certificate in the request. If there is a match and the OCSPSigning
|
||||
extended key usage is present in the OCSP responder certificate then the
|
||||
OCSP verify succeeds.
|
||||
|
||||
Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders
|
||||
CA is checked to see if it is trusted for OCSP signing. If it is the OCSP
|
||||
verify succeeds.
|
||||
|
||||
If none of these checks is successful then the OCSP verify fails.
|
||||
|
||||
What this effectively means if that if the OCSP responder certificate is
|
||||
authorised directly by the CA it is issuing revocation information about
|
||||
(and it is correctly configured) then verification will succeed.
|
||||
|
||||
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
|
||||
|
||||
Alternatively the responder certificate itself can be explicitly trusted
|
||||
with the B<-VAfile> option.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
As noted, most of the verify options are for testing or debugging purposes.
|
||||
Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global
|
||||
VA') B<-VAfile> options need to be used.
|
||||
|
||||
The OCSP server is only useful for test and demonstration purposes: it is
|
||||
not really usable as a full OCSP responder. It contains only a very
|
||||
simple HTTP request handling and can only handle the POST form of OCSP
|
||||
queries. It also handles requests serially meaning it cannot respond to
|
||||
new requests until it has processed the current one. The text index file
|
||||
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<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
|
||||
|
||||
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 \
|
||||
-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 -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
|
||||
|
||||
As above but exit after processing one request:
|
||||
|
||||
openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
|
||||
-nrequest 1
|
||||
|
||||
Query status information using an internally generated request:
|
||||
|
||||
openssl 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, and write the response
|
||||
to a second file.
|
||||
|
||||
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
|
||||
-reqin req.der -respout resp.der
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The -no_alt_chains option was added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2001-2020 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
|
||||
@@ -0,0 +1,568 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl - OpenSSL command line tool
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl>
|
||||
I<command>
|
||||
[ I<command_opts> ]
|
||||
[ I<command_args> ]
|
||||
|
||||
B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<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).
|
||||
|
||||
Detailed documentation and use cases for most standard subcommands are available
|
||||
(e.g., L<x509(1)> or L<openssl-x509(1)>).
|
||||
|
||||
Many commands use an external configuration file for some or all of their
|
||||
arguments and have a B<-config> option to specify that file.
|
||||
The environment variable B<OPENSSL_CONF> can be used to specify
|
||||
the location of the file.
|
||||
If the environment variable is not specified, then the file is named
|
||||
B<openssl.cnf> in the default certificate storage area, whose value
|
||||
depends on the configuration flags specified when the OpenSSL
|
||||
was built.
|
||||
|
||||
The list parameters B<standard-commands>, B<digest-commands>,
|
||||
and B<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 list parameters B<cipher-algorithms> and
|
||||
B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
|
||||
|
||||
from => to
|
||||
|
||||
The list parameter B<public-key-algorithms> lists all supported public
|
||||
key algorithms.
|
||||
|
||||
The 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>, or B<no->I<XXX> itself.)
|
||||
|
||||
=head2 Standard Commands
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<asn1parse>
|
||||
|
||||
Parse an ASN.1 sequence.
|
||||
|
||||
=item B<ca>
|
||||
|
||||
Certificate Authority (CA) Management.
|
||||
|
||||
=item B<ciphers>
|
||||
|
||||
Cipher Suite Description Determination.
|
||||
|
||||
=item B<cms>
|
||||
|
||||
CMS (Cryptographic Message Syntax) utility.
|
||||
|
||||
=item B<crl>
|
||||
|
||||
Certificate Revocation List (CRL) Management.
|
||||
|
||||
=item B<crl2pkcs7>
|
||||
|
||||
CRL to PKCS#7 Conversion.
|
||||
|
||||
=item B<dgst>
|
||||
|
||||
Message Digest Calculation.
|
||||
|
||||
=item B<dh>
|
||||
|
||||
Diffie-Hellman Parameter Management.
|
||||
Obsoleted by L<dhparam(1)>.
|
||||
|
||||
=item B<dhparam>
|
||||
|
||||
Generation and Management of Diffie-Hellman Parameters. Superseded by
|
||||
L<genpkey(1)> and L<pkeyparam(1)>.
|
||||
|
||||
=item B<dsa>
|
||||
|
||||
DSA Data Management.
|
||||
|
||||
=item B<dsaparam>
|
||||
|
||||
DSA Parameter Generation and Management. Superseded by
|
||||
L<genpkey(1)> and L<pkeyparam(1)>.
|
||||
|
||||
=item B<ec>
|
||||
|
||||
EC (Elliptic curve) key processing.
|
||||
|
||||
=item B<ecparam>
|
||||
|
||||
EC parameter manipulation and generation.
|
||||
|
||||
=item B<enc>
|
||||
|
||||
Encoding with Ciphers.
|
||||
|
||||
=item B<engine>
|
||||
|
||||
Engine (loadable module) information and manipulation.
|
||||
|
||||
=item B<errstr>
|
||||
|
||||
Error Number to Error String Conversion.
|
||||
|
||||
=item B<gendh>
|
||||
|
||||
Generation of Diffie-Hellman Parameters.
|
||||
Obsoleted by L<dhparam(1)>.
|
||||
|
||||
=item B<gendsa>
|
||||
|
||||
Generation of DSA Private Key from Parameters. Superseded by
|
||||
L<genpkey(1)> and L<pkey(1)>.
|
||||
|
||||
=item B<genpkey>
|
||||
|
||||
Generation of Private Key or Parameters.
|
||||
|
||||
=item B<genrsa>
|
||||
|
||||
Generation of RSA Private Key. Superseded by L<genpkey(1)>.
|
||||
|
||||
=item B<nseq>
|
||||
|
||||
Create or examine a Netscape certificate sequence.
|
||||
|
||||
=item B<ocsp>
|
||||
|
||||
Online Certificate Status Protocol utility.
|
||||
|
||||
=item B<passwd>
|
||||
|
||||
Generation of hashed passwords.
|
||||
|
||||
=item B<pkcs12>
|
||||
|
||||
PKCS#12 Data Management.
|
||||
|
||||
=item B<pkcs7>
|
||||
|
||||
PKCS#7 Data Management.
|
||||
|
||||
=item B<pkcs8>
|
||||
|
||||
PKCS#8 format private key conversion tool.
|
||||
|
||||
=item B<pkey>
|
||||
|
||||
Public and private key management.
|
||||
|
||||
=item B<pkeyparam>
|
||||
|
||||
Public key algorithm parameter management.
|
||||
|
||||
=item B<pkeyutl>
|
||||
|
||||
Public key algorithm cryptographic operation utility.
|
||||
|
||||
=item B<prime>
|
||||
|
||||
Compute prime numbers.
|
||||
|
||||
=item B<rand>
|
||||
|
||||
Generate pseudo-random bytes.
|
||||
|
||||
=item B<rehash>
|
||||
|
||||
Create symbolic links to certificate and CRL files named by the hash values.
|
||||
|
||||
=item B<req>
|
||||
|
||||
PKCS#10 X.509 Certificate Signing Request (CSR) Management.
|
||||
|
||||
=item B<rsa>
|
||||
|
||||
RSA key management.
|
||||
|
||||
=item B<rsautl>
|
||||
|
||||
RSA utility for signing, verification, encryption, and decryption. Superseded
|
||||
by L<pkeyutl(1)>.
|
||||
|
||||
=item B<s_client>
|
||||
|
||||
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 B<s_server>
|
||||
|
||||
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 B<s_time>
|
||||
|
||||
SSL Connection Timer.
|
||||
|
||||
=item B<sess_id>
|
||||
|
||||
SSL Session Data Management.
|
||||
|
||||
=item B<smime>
|
||||
|
||||
S/MIME mail processing.
|
||||
|
||||
=item B<speed>
|
||||
|
||||
Algorithm Speed Measurement.
|
||||
|
||||
=item B<spkac>
|
||||
|
||||
SPKAC printing and generating utility.
|
||||
|
||||
=item B<srp>
|
||||
|
||||
Maintain SRP password file.
|
||||
|
||||
=item B<storeutl>
|
||||
|
||||
Utility to list and display certificates, keys, CRLs, etc.
|
||||
|
||||
=item B<ts>
|
||||
|
||||
Time Stamping Authority tool (client/server).
|
||||
|
||||
=item B<verify>
|
||||
|
||||
X.509 Certificate Verification.
|
||||
|
||||
=item B<version>
|
||||
|
||||
OpenSSL Version Information.
|
||||
|
||||
=item B<x509>
|
||||
|
||||
X.509 Certificate Data Management.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Message Digest Commands
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<blake2b512>
|
||||
|
||||
BLAKE2b-512 Digest
|
||||
|
||||
=item B<blake2s256>
|
||||
|
||||
BLAKE2s-256 Digest
|
||||
|
||||
=item B<md2>
|
||||
|
||||
MD2 Digest
|
||||
|
||||
=item B<md4>
|
||||
|
||||
MD4 Digest
|
||||
|
||||
=item B<md5>
|
||||
|
||||
MD5 Digest
|
||||
|
||||
=item B<mdc2>
|
||||
|
||||
MDC2 Digest
|
||||
|
||||
=item B<rmd160>
|
||||
|
||||
RMD-160 Digest
|
||||
|
||||
=item B<sha1>
|
||||
|
||||
SHA-1 Digest
|
||||
|
||||
=item B<sha224>
|
||||
|
||||
SHA-2 224 Digest
|
||||
|
||||
=item B<sha256>
|
||||
|
||||
SHA-2 256 Digest
|
||||
|
||||
=item B<sha384>
|
||||
|
||||
SHA-2 384 Digest
|
||||
|
||||
=item B<sha512>
|
||||
|
||||
SHA-2 512 Digest
|
||||
|
||||
=item B<sha3-224>
|
||||
|
||||
SHA-3 224 Digest
|
||||
|
||||
=item B<sha3-256>
|
||||
|
||||
SHA-3 256 Digest
|
||||
|
||||
=item B<sha3-384>
|
||||
|
||||
SHA-3 384 Digest
|
||||
|
||||
=item B<sha3-512>
|
||||
|
||||
SHA-3 512 Digest
|
||||
|
||||
=item B<shake128>
|
||||
|
||||
SHA-3 SHAKE128 Digest
|
||||
|
||||
=item B<shake256>
|
||||
|
||||
SHA-3 SHAKE256 Digest
|
||||
|
||||
=item B<sm3>
|
||||
|
||||
SM3 Digest
|
||||
|
||||
=back
|
||||
|
||||
=head2 Encoding and Cipher Commands
|
||||
|
||||
The following aliases provide convenient access to the most used encodings
|
||||
and ciphers.
|
||||
|
||||
Depending on how OpenSSL was configured and built, not all ciphers listed
|
||||
here may be present. See L<enc(1)> for more information and command usage.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<aes128>, B<aes-128-cbc>, B<aes-128-cfb>, B<aes-128-ctr>, B<aes-128-ecb>, B<aes-128-ofb>
|
||||
|
||||
AES-128 Cipher
|
||||
|
||||
=item B<aes192>, B<aes-192-cbc>, B<aes-192-cfb>, B<aes-192-ctr>, B<aes-192-ecb>, B<aes-192-ofb>
|
||||
|
||||
AES-192 Cipher
|
||||
|
||||
=item B<aes256>, B<aes-256-cbc>, B<aes-256-cfb>, B<aes-256-ctr>, B<aes-256-ecb>, B<aes-256-ofb>
|
||||
|
||||
AES-256 Cipher
|
||||
|
||||
=item B<aria128>, B<aria-128-cbc>, B<aria-128-cfb>, B<aria-128-ctr>, B<aria-128-ecb>, B<aria-128-ofb>
|
||||
|
||||
Aria-128 Cipher
|
||||
|
||||
=item B<aria192>, B<aria-192-cbc>, B<aria-192-cfb>, B<aria-192-ctr>, B<aria-192-ecb>, B<aria-192-ofb>
|
||||
|
||||
Aria-192 Cipher
|
||||
|
||||
=item B<aria256>, B<aria-256-cbc>, B<aria-256-cfb>, B<aria-256-ctr>, B<aria-256-ecb>, B<aria-256-ofb>
|
||||
|
||||
Aria-256 Cipher
|
||||
|
||||
=item B<base64>
|
||||
|
||||
Base64 Encoding
|
||||
|
||||
=item B<bf>, B<bf-cbc>, B<bf-cfb>, B<bf-ecb>, B<bf-ofb>
|
||||
|
||||
Blowfish Cipher
|
||||
|
||||
=item B<camellia128>, B<camellia-128-cbc>, B<camellia-128-cfb>, B<camellia-128-ctr>, B<camellia-128-ecb>, B<camellia-128-ofb>
|
||||
|
||||
Camellia-128 Cipher
|
||||
|
||||
=item B<camellia192>, B<camellia-192-cbc>, B<camellia-192-cfb>, B<camellia-192-ctr>, B<camellia-192-ecb>, B<camellia-192-ofb>
|
||||
|
||||
Camellia-192 Cipher
|
||||
|
||||
=item B<camellia256>, B<camellia-256-cbc>, B<camellia-256-cfb>, B<camellia-256-ctr>, B<camellia-256-ecb>, B<camellia-256-ofb>
|
||||
|
||||
Camellia-256 Cipher
|
||||
|
||||
=item B<cast>, B<cast-cbc>
|
||||
|
||||
CAST Cipher
|
||||
|
||||
=item B<cast5-cbc>, B<cast5-cfb>, B<cast5-ecb>, B<cast5-ofb>
|
||||
|
||||
CAST5 Cipher
|
||||
|
||||
=item B<chacha20>
|
||||
|
||||
Chacha20 Cipher
|
||||
|
||||
=item B<des>, B<des-cbc>, B<des-cfb>, B<des-ecb>, B<des-ede>, B<des-ede-cbc>, B<des-ede-cfb>, B<des-ede-ofb>, B<des-ofb>
|
||||
|
||||
DES Cipher
|
||||
|
||||
=item B<des3>, B<desx>, B<des-ede3>, B<des-ede3-cbc>, B<des-ede3-cfb>, B<des-ede3-ofb>
|
||||
|
||||
Triple-DES Cipher
|
||||
|
||||
=item B<idea>, B<idea-cbc>, B<idea-cfb>, B<idea-ecb>, B<idea-ofb>
|
||||
|
||||
IDEA Cipher
|
||||
|
||||
=item B<rc2>, B<rc2-cbc>, B<rc2-cfb>, B<rc2-ecb>, B<rc2-ofb>
|
||||
|
||||
RC2 Cipher
|
||||
|
||||
=item B<rc4>
|
||||
|
||||
RC4 Cipher
|
||||
|
||||
=item B<rc5>, B<rc5-cbc>, B<rc5-cfb>, B<rc5-ecb>, B<rc5-ofb>
|
||||
|
||||
RC5 Cipher
|
||||
|
||||
=item B<seed>, B<seed-cbc>, B<seed-cfb>, B<seed-ecb>, B<seed-ofb>
|
||||
|
||||
SEED Cipher
|
||||
|
||||
=item B<sm4>, B<sm4-cbc>, B<sm4-cfb>, B<sm4-ctr>, B<sm4-ecb>, B<sm4-ofb>
|
||||
|
||||
SM4 Cipher
|
||||
|
||||
=back
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
Details of which options are available depend on the specific command.
|
||||
This section describes some common options with common behavior.
|
||||
|
||||
=head2 Common Options
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Provides a terse summary of all options.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Pass Phrase Options
|
||||
|
||||
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.
|
||||
|
||||
Note that character encoding may be relevant, please see
|
||||
L<passphrase-encoding(7)>.
|
||||
|
||||
=over 4
|
||||
|
||||
=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)>, L<ca(1)>, L<ciphers(1)>, L<cms(1)>, L<config(5)>,
|
||||
L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
|
||||
L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
|
||||
L<ec(1)>, L<ecparam(1)>,
|
||||
L<enc(1)>, L<engine(1)>, L<errstr(1)>, L<gendsa(1)>, L<genpkey(1)>,
|
||||
L<genrsa(1)>, L<nseq(1)>, L<ocsp(1)>,
|
||||
L<passwd(1)>,
|
||||
L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,
|
||||
L<pkey(1)>, L<pkeyparam(1)>, L<pkeyutl(1)>, L<prime(1)>,
|
||||
L<rand(1)>, L<rehash(1)>, L<req(1)>, L<rsa(1)>,
|
||||
L<rsautl(1)>, L<s_client(1)>,
|
||||
L<s_server(1)>, L<s_time(1)>, L<sess_id(1)>,
|
||||
L<smime(1)>, L<speed(1)>, L<spkac(1)>, L<srp(1)>, L<storeutl(1)>,
|
||||
L<ts(1)>,
|
||||
L<verify(1)>, L<version(1)>, L<x509(1)>,
|
||||
L<crypto(7)>, L<ssl(7)>, L<x509v3_config(5)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0;
|
||||
For notes on the availability of other commands, see their individual
|
||||
manual pages.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 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
|
||||
@@ -0,0 +1,132 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-passwd,
|
||||
passwd - compute password hashes
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl passwd>
|
||||
[B<-help>]
|
||||
[B<-crypt>]
|
||||
[B<-1>]
|
||||
[B<-apr1>]
|
||||
[B<-aixmd5>]
|
||||
[B<-5>]
|
||||
[B<-6>]
|
||||
[B<-salt> I<string>]
|
||||
[B<-in> I<file>]
|
||||
[B<-stdin>]
|
||||
[B<-noverify>]
|
||||
[B<-quiet>]
|
||||
[B<-table>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
{I<password>}
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<passwd> command computes the hash of a password typed at
|
||||
run-time or the hash of each password in a list. The password list is
|
||||
taken from the named file for option B<-in file>, from stdin for
|
||||
option B<-stdin>, or from the command line, or from the terminal otherwise.
|
||||
The Unix standard algorithm B<crypt> and the MD5-based BSD password
|
||||
algorithm B<1>, its Apache variant B<apr1>, and its AIX variant are available.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Print out a usage message.
|
||||
|
||||
=item B<-crypt>
|
||||
|
||||
Use the B<crypt> algorithm (default).
|
||||
|
||||
=item B<-1>
|
||||
|
||||
Use the MD5 based BSD password algorithm B<1>.
|
||||
|
||||
=item B<-apr1>
|
||||
|
||||
Use the B<apr1> algorithm (Apache variant of the BSD algorithm).
|
||||
|
||||
=item B<-aixmd5>
|
||||
|
||||
Use the B<AIX MD5> algorithm (AIX variant of the BSD algorithm).
|
||||
|
||||
=item B<-5>
|
||||
|
||||
=item B<-6>
|
||||
|
||||
Use the B<SHA256> / B<SHA512> based algorithms defined by Ulrich Drepper.
|
||||
See L<https://www.akkadia.org/drepper/SHA-crypt.txt>.
|
||||
|
||||
=item B<-salt> I<string>
|
||||
|
||||
Use the specified salt.
|
||||
When reading a password from the terminal, this implies B<-noverify>.
|
||||
|
||||
=item B<-in> I<file>
|
||||
|
||||
Read passwords from I<file>.
|
||||
|
||||
=item B<-stdin>
|
||||
|
||||
Read passwords from B<stdin>.
|
||||
|
||||
=item B<-noverify>
|
||||
|
||||
Don't verify when reading a password from the terminal.
|
||||
|
||||
=item B<-quiet>
|
||||
|
||||
Don't output warnings when passwords given at the command line are truncated.
|
||||
|
||||
=item B<-table>
|
||||
|
||||
In the output list, prepend the cleartext password and a TAB character
|
||||
to each password hash.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
% openssl passwd -crypt -salt xx password
|
||||
xxj31ZMTZzkVA
|
||||
|
||||
% openssl passwd -1 -salt xxxxxxxx password
|
||||
$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.
|
||||
|
||||
% openssl passwd -apr1 -salt xxxxxxxx password
|
||||
$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0
|
||||
|
||||
% openssl passwd -aixmd5 -salt xxxxxxxx password
|
||||
xxxxxxxx$8Oaipk/GPKhC64w/YVeFD/
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 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
|
||||
@@ -0,0 +1,389 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-pkcs12,
|
||||
pkcs12 - PKCS#12 file utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<pkcs12>
|
||||
[B<-help>]
|
||||
[B<-export>]
|
||||
[B<-chain>]
|
||||
[B<-inkey file_or_id>]
|
||||
[B<-certfile filename>]
|
||||
[B<-name name>]
|
||||
[B<-caname name>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-noout>]
|
||||
[B<-nomacver>]
|
||||
[B<-nocerts>]
|
||||
[B<-clcerts>]
|
||||
[B<-cacerts>]
|
||||
[B<-nokeys>]
|
||||
[B<-info>]
|
||||
[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -aria128 | -aria192 | -aria256 | -camellia128 | -camellia192 | -camellia256 | -nodes>]
|
||||
[B<-noiter>]
|
||||
[B<-maciter | -nomaciter | -nomac>]
|
||||
[B<-twopass>]
|
||||
[B<-descert>]
|
||||
[B<-certpbe cipher>]
|
||||
[B<-keypbe cipher>]
|
||||
[B<-macalg digest>]
|
||||
[B<-keyex>]
|
||||
[B<-keysig>]
|
||||
[B<-password arg>]
|
||||
[B<-passin arg>]
|
||||
[B<-passout arg>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-CAfile file>]
|
||||
[B<-CApath dir>]
|
||||
[B<-no-CAfile>]
|
||||
[B<-no-CApath>]
|
||||
[B<-CSP name>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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 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
|
||||
file can be created by using the B<-export> option (see below).
|
||||
|
||||
=head1 PARSING OPTIONS
|
||||
|
||||
=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
|
||||
by default.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
The filename to write certificates and private keys to, standard output by
|
||||
default. They are all written in PEM format.
|
||||
|
||||
=item B<-passin arg>
|
||||
|
||||
The PKCS#12 file (i.e. input file) password source. For more information about
|
||||
the format of B<arg> see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-passout arg>
|
||||
|
||||
Pass phrase source to encrypt any outputted private keys with. For more
|
||||
information about the format of B<arg> see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-password arg>
|
||||
|
||||
With -export, -password is equivalent to -passout.
|
||||
Otherwise, -password is equivalent to -passin.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
This option inhibits output of the keys and certificates to the output file
|
||||
version of the PKCS#12 file.
|
||||
|
||||
=item B<-clcerts>
|
||||
|
||||
Only output client certificates (not CA certificates).
|
||||
|
||||
=item B<-cacerts>
|
||||
|
||||
Only output CA certificates (not client certificates).
|
||||
|
||||
=item B<-nocerts>
|
||||
|
||||
No certificates at all will be output.
|
||||
|
||||
=item B<-nokeys>
|
||||
|
||||
No private keys will be output.
|
||||
|
||||
=item B<-info>
|
||||
|
||||
Output additional information about the PKCS#12 file structure, algorithms
|
||||
used and iteration counts.
|
||||
|
||||
=item B<-des>
|
||||
|
||||
Use DES to encrypt private keys before outputting.
|
||||
|
||||
=item B<-des3>
|
||||
|
||||
Use triple DES to encrypt private keys before outputting, this is the default.
|
||||
|
||||
=item B<-idea>
|
||||
|
||||
Use IDEA to encrypt private keys before outputting.
|
||||
|
||||
=item B<-aes128>, B<-aes192>, B<-aes256>
|
||||
|
||||
Use AES to encrypt private keys before outputting.
|
||||
|
||||
=item B<-aria128>, B<-aria192>, B<-aria256>
|
||||
|
||||
Use ARIA to encrypt private keys before outputting.
|
||||
|
||||
=item B<-camellia128>, B<-camellia192>, B<-camellia256>
|
||||
|
||||
Use Camellia to encrypt private keys before outputting.
|
||||
|
||||
=item B<-nodes>
|
||||
|
||||
Don't encrypt the private keys at all.
|
||||
|
||||
=item B<-nomacver>
|
||||
|
||||
Don't attempt to verify the integrity MAC before reading the file.
|
||||
|
||||
=item B<-twopass>
|
||||
|
||||
Prompt for separate integrity and encryption passwords: most software
|
||||
always assumes these are the same so this option will render such
|
||||
PKCS#12 files unreadable. Cannot be used in combination with the options
|
||||
-password, -passin (if importing) or -passout (if exporting).
|
||||
|
||||
=back
|
||||
|
||||
=head1 FILE CREATION OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-export>
|
||||
|
||||
This option specifies that a PKCS#12 file will be created rather than
|
||||
parsed.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies filename to write the PKCS#12 file to. Standard output is used
|
||||
by default.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
The filename to read certificates and private keys from, standard input by
|
||||
default. They must all be in PEM format. The order doesn't matter but one
|
||||
private key and its corresponding certificate should be present. If additional
|
||||
certificates are present they will also be included in the PKCS#12 file.
|
||||
|
||||
=item B<-inkey file_or_id>
|
||||
|
||||
File to read private key from. If not present then a private key must be present
|
||||
in the input file.
|
||||
If no engine is used, the argument is taken as a file; if an engine is
|
||||
specified, the argument is given to the engine as a key identifier.
|
||||
|
||||
=item B<-name friendlyname>
|
||||
|
||||
This specifies the "friendly name" for the certificate and private key. This
|
||||
name is typically displayed in list boxes by software importing the file.
|
||||
|
||||
=item B<-certfile filename>
|
||||
|
||||
A filename to read additional certificates from.
|
||||
|
||||
=item B<-caname friendlyname>
|
||||
|
||||
This specifies the "friendly name" for other certificates. This option may be
|
||||
used multiple times to specify names for all certificates in the order they
|
||||
appear. Netscape ignores friendly names on other certificates whereas MSIE
|
||||
displays them.
|
||||
|
||||
=item B<-pass arg>, B<-passout arg>
|
||||
|
||||
The PKCS#12 file (i.e. output file) password source. For more information about
|
||||
the format of B<arg> see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-passin password>
|
||||
|
||||
Pass phrase source to decrypt any input private keys with. For more information
|
||||
about the format of B<arg> see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-chain>
|
||||
|
||||
If this option is present then an attempt is made to include the entire
|
||||
certificate chain of the user certificate. The standard CA store is used
|
||||
for this search. If the search fails it is considered a fatal error.
|
||||
|
||||
=item B<-descert>
|
||||
|
||||
Encrypt the certificate using triple DES, this may render the PKCS#12
|
||||
file unreadable by some "export grade" software. By default the private
|
||||
key is encrypted using triple DES and the certificate using 40 bit RC2
|
||||
unless RC2 is disabled in which case triple DES is used.
|
||||
|
||||
=item B<-keypbe alg>, B<-certpbe alg>
|
||||
|
||||
These options allow the algorithm used to encrypt the private key and
|
||||
certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name
|
||||
can be used (see B<NOTES> section for more information). If a cipher name
|
||||
(as output by the B<list-cipher-algorithms> command is specified then it
|
||||
is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only
|
||||
use PKCS#12 algorithms.
|
||||
|
||||
=item B<-keyex|-keysig>
|
||||
|
||||
Specifies that the private key is to be used for key exchange or just signing.
|
||||
This option is only interpreted by MSIE and similar MS software. Normally
|
||||
"export grade" software will only allow 512 bit RSA keys to be used for
|
||||
encryption purposes but arbitrary length keys for signing. The B<-keysig>
|
||||
option marks the key for signing only. Signing only keys can be used for
|
||||
S/MIME signing, authenticode (ActiveX control signing) and SSL client
|
||||
authentication, however, due to a bug only MSIE 5.0 and later support
|
||||
the use of signing only keys for SSL client authentication.
|
||||
|
||||
=item B<-macalg digest>
|
||||
|
||||
Specify the MAC digest algorithm. If not included them SHA1 will be used.
|
||||
|
||||
=item B<-nomaciter>, B<-noiter>
|
||||
|
||||
These options affect the iteration counts on the MAC and key algorithms.
|
||||
Unless you wish to produce files compatible with MSIE 4.0 you should leave
|
||||
these options alone.
|
||||
|
||||
To discourage attacks by using large dictionaries of common passwords the
|
||||
algorithm that derives keys from passwords can have an iteration count applied
|
||||
to it: this causes a certain part of the algorithm to be repeated and slows it
|
||||
down. The MAC is used to check the file integrity but since it will normally
|
||||
have the same password as the keys and certificates it could also be attacked.
|
||||
By default both MAC and encryption iteration counts are set to 2048, using
|
||||
these options the MAC and encryption iteration counts can be set to 1, since
|
||||
this reduces the file security you should not use these options unless you
|
||||
really have to. Most software supports both MAC and key iteration counts.
|
||||
MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter>
|
||||
option.
|
||||
|
||||
=item B<-maciter>
|
||||
|
||||
This option is included for compatibility with previous versions, it used
|
||||
to be needed to use MAC iterations counts but they are now used by default.
|
||||
|
||||
=item B<-nomac>
|
||||
|
||||
Don't attempt to provide the MAC integrity.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-CAfile file>
|
||||
|
||||
CA storage as a file.
|
||||
|
||||
=item B<-CApath dir>
|
||||
|
||||
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.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Although there are a large number of options most of them are very rarely
|
||||
used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
|
||||
for PKCS#12 file creation B<-export> and B<-name> are also used.
|
||||
|
||||
If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present
|
||||
then all certificates will be output in the order they appear in the input
|
||||
PKCS#12 files. There is no guarantee that the first certificate present is
|
||||
the one corresponding to the private key. Certain software which requires
|
||||
a private key and certificate and assumes the first certificate in the
|
||||
file is the one corresponding to the private key: this may not always
|
||||
be the case. Using the B<-clcerts> option will solve this problem by only
|
||||
outputting the certificate corresponding to the private key. If the CA
|
||||
certificates are required then they can be output to a separate file using
|
||||
the B<-nokeys -cacerts> options to just output CA certificates.
|
||||
|
||||
The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption
|
||||
algorithms for private keys and certificates to be specified. Normally
|
||||
the defaults are fine but occasionally software can't handle triple DES
|
||||
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
|
||||
|
||||
Output only client certificates to a file:
|
||||
|
||||
openssl pkcs12 -in file.p12 -clcerts -out file.pem
|
||||
|
||||
Don't encrypt the private key:
|
||||
|
||||
openssl pkcs12 -in file.p12 -out file.pem -nodes
|
||||
|
||||
Print some info about a PKCS#12 file:
|
||||
|
||||
openssl pkcs12 -in file.p12 -info -noout
|
||||
|
||||
Create a PKCS#12 file:
|
||||
|
||||
openssl 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" \
|
||||
-certfile othercerts.pem
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<pkcs8(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,120 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-pkcs7,
|
||||
pkcs7 - PKCS#7 utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<pkcs7>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-print_certs>]
|
||||
[B<-text>]
|
||||
[B<-noout>]
|
||||
[B<-engine id>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
|
||||
|
||||
=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
|
||||
v1.5 structure.B<PEM> (the default) is a base64 encoded version of
|
||||
the DER form with header and footer lines.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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<-print_certs>
|
||||
|
||||
Prints out any certificates or CRLs contained in the file. They are
|
||||
preceded by their subject and issuer names in one line format.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
Prints out certificates details in full rather than just subject and
|
||||
issuer names.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
Don't output the encoded version of the PKCS#7 structure (or certificates
|
||||
is B<-print_certs> is set).
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<pkcs7>
|
||||
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 EXAMPLES
|
||||
|
||||
Convert a PKCS#7 file from PEM to DER:
|
||||
|
||||
openssl 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
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The PEM PKCS#7 format uses the header and footer lines:
|
||||
|
||||
-----BEGIN PKCS7-----
|
||||
-----END PKCS7-----
|
||||
|
||||
For compatibility with some CAs it will also accept:
|
||||
|
||||
-----BEGIN CERTIFICATE-----
|
||||
-----END CERTIFICATE-----
|
||||
|
||||
=head1 RESTRICTIONS
|
||||
|
||||
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
|
||||
cannot currently parse, for example, the new CMS as described in RFC2630.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<crl2pkcs7(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 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
|
||||
@@ -0,0 +1,319 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-pkcs8,
|
||||
pkcs8 - PKCS#8 format private key conversion tool
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<pkcs8>
|
||||
[B<-help>]
|
||||
[B<-topk8>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-passin arg>]
|
||||
[B<-out filename>]
|
||||
[B<-passout arg>]
|
||||
[B<-iter count>]
|
||||
[B<-noiter>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-nocrypt>]
|
||||
[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
|
||||
|
||||
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 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 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: see L<KEY FORMATS> for more details. The default
|
||||
format is PEM.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format: see L<KEY FORMATS> for more details. The default
|
||||
format is PEM.
|
||||
|
||||
=item B<-traditional>
|
||||
|
||||
When this option is present and B<-topk8> is not a traditional format private
|
||||
key is written.
|
||||
|
||||
=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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write a key to or standard output by
|
||||
default. 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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=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>
|
||||
|
||||
PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
|
||||
structures using an appropriate password based encryption algorithm. With
|
||||
this option an unencrypted PrivateKeyInfo structure is expected or output.
|
||||
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<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-v2 alg>
|
||||
|
||||
This option sets the PKCS#5 v2.0 algorithm.
|
||||
|
||||
The B<alg> argument is the encryption algorithm to use, valid values include
|
||||
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
|
||||
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 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>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<pkcs8>
|
||||
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.
|
||||
|
||||
=item 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:
|
||||
|
||||
-----BEGIN ENCRYPTED PRIVATE KEY-----
|
||||
-----END ENCRYPTED PRIVATE KEY-----
|
||||
|
||||
The unencrypted form uses:
|
||||
|
||||
-----BEGIN PRIVATE KEY-----
|
||||
-----END PRIVATE KEY-----
|
||||
|
||||
Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
|
||||
|
||||
Various algorithms can be used with the B<-v1> command line option,
|
||||
including PKCS#5 v1.5 and PKCS#12. These are described in more detail
|
||||
below.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<PBE-MD2-DES PBE-MD5-DES>
|
||||
|
||||
These algorithms were included in the original PKCS#5 v1.5 specification.
|
||||
They only offer 56 bits of protection since they both use DES.
|
||||
|
||||
=item B<PBE-SHA1-RC2-64>, B<PBE-MD2-RC2-64>, B<PBE-MD5-RC2-64>, B<PBE-SHA1-DES>
|
||||
|
||||
These algorithms are not mentioned in the original PKCS#5 v1.5 specification
|
||||
but they use the same key derivation algorithm and are supported by some
|
||||
software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
|
||||
56 bit DES.
|
||||
|
||||
=item B<PBE-SHA1-RC4-128>, B<PBE-SHA1-RC4-40>, B<PBE-SHA1-3DES>, B<PBE-SHA1-2DES>, B<PBE-SHA1-RC2-128>, B<PBE-SHA1-RC2-40>
|
||||
|
||||
These algorithms use the PKCS#12 password based encryption algorithm and
|
||||
allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
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 -out enckey.pem
|
||||
|
||||
Convert a private key to PKCS#8 unencrypted format:
|
||||
|
||||
openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
|
||||
|
||||
Convert a private key to PKCS#5 v2.0 format using triple DES:
|
||||
|
||||
openssl 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:
|
||||
|
||||
openssl 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 -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
|
||||
|
||||
Read a DER unencrypted PKCS#8 format private key:
|
||||
|
||||
openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
|
||||
|
||||
Convert a private key from any PKCS#8 encrypted format to traditional format:
|
||||
|
||||
openssl 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:
|
||||
|
||||
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
|
||||
|
||||
=head1 STANDARDS
|
||||
|
||||
Test vectors from this PKCS#5 v2.0 implementation were posted to the
|
||||
pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
|
||||
counts, several people confirmed that they could decrypt the private
|
||||
keys produced and therefore, it can be assumed that the PKCS#5 v2.0
|
||||
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
|
||||
PKCS#8 private key format complies with this standard.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
There should be an option that prints out the encryption algorithm
|
||||
in use and other details such as the iteration count.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
|
||||
L<gendsa(1)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The B<-iter> option was added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,168 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-pkey,
|
||||
pkey - public or private key processing tool
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> 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<-I<cipher>>]
|
||||
[B<-text>]
|
||||
[B<-text_pub>]
|
||||
[B<-noout>]
|
||||
[B<-pubin>]
|
||||
[B<-pubout>]
|
||||
[B<-engine id>]
|
||||
[B<-check>]
|
||||
[B<-pubcheck>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<pkey> command processes public or private keys. They can be converted
|
||||
between various forms and their components printed out.
|
||||
|
||||
=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. The default format is PEM.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write a key to or standard output if this
|
||||
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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-I<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>.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
Prints out the various public or private key components in
|
||||
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>
|
||||
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<-check>
|
||||
|
||||
This option checks the consistency of a key pair for both public and private
|
||||
components.
|
||||
|
||||
=item B<-pubcheck>
|
||||
|
||||
This option checks the correctness of either a public key or the public component
|
||||
of a key pair.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To remove the pass phrase on an RSA private key:
|
||||
|
||||
openssl pkey -in key.pem -out keyout.pem
|
||||
|
||||
To encrypt a private key using triple DES:
|
||||
|
||||
openssl pkey -in key.pem -des3 -out keyout.pem
|
||||
|
||||
To convert a private key from PEM to DER format:
|
||||
|
||||
openssl 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
|
||||
|
||||
To print out the public components of a private key to standard output:
|
||||
|
||||
openssl 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
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
|
||||
L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2006-2021 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
|
||||
@@ -0,0 +1,88 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-pkeyparam,
|
||||
pkeyparam - public key algorithm parameter processing tool
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<pkeyparam>
|
||||
[B<-help>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-text>]
|
||||
[B<-noout>]
|
||||
[B<-engine id>]
|
||||
[B<-check>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<pkeyparam> command processes public key algorithm parameters.
|
||||
They can be checked for correctness and their components printed out.
|
||||
|
||||
=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
|
||||
this option is not specified.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write parameters to or standard output if
|
||||
this option is not specified.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
Prints out the parameters in plain text in addition to the encoded version.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
Do not output the encoded version of the parameters.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<pkeyparam>
|
||||
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<-check>
|
||||
|
||||
This option checks the correctness of parameters.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Print out text version of parameters:
|
||||
|
||||
openssl pkeyparam -in param.pem -text
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
There are no B<-inform> or B<-outform> options for this command because only
|
||||
PEM format is supported because the key type is determined by the PEM headers.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
|
||||
L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2006-2019 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
|
||||
@@ -0,0 +1,337 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-pkeyutl,
|
||||
pkeyutl - public key algorithm utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<pkeyutl>
|
||||
[B<-help>]
|
||||
[B<-in file>]
|
||||
[B<-out file>]
|
||||
[B<-sigfile file>]
|
||||
[B<-inkey file>]
|
||||
[B<-keyform PEM|DER|ENGINE>]
|
||||
[B<-passin arg>]
|
||||
[B<-peerkey file>]
|
||||
[B<-peerform PEM|DER|ENGINE>]
|
||||
[B<-pubin>]
|
||||
[B<-certin>]
|
||||
[B<-rev>]
|
||||
[B<-sign>]
|
||||
[B<-verify>]
|
||||
[B<-verifyrecover>]
|
||||
[B<-encrypt>]
|
||||
[B<-decrypt>]
|
||||
[B<-derive>]
|
||||
[B<-kdf algorithm>]
|
||||
[B<-kdflen length>]
|
||||
[B<-pkeyopt opt:value>]
|
||||
[B<-hexdump>]
|
||||
[B<-asn1parse>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-engine id>]
|
||||
[B<-engine_impl>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<pkeyutl> command can be used to perform low-level public key operations
|
||||
using any supported algorithm.
|
||||
|
||||
=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
|
||||
if this option is not specified.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
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|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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-peerkey file>
|
||||
|
||||
The peer key file, used by key derivation (agreement) operations.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-certin>
|
||||
|
||||
The input is a certificate containing a public key.
|
||||
|
||||
=item B<-rev>
|
||||
|
||||
Reverse the order of the input buffer. This is useful for some libraries
|
||||
(such as CryptoAPI) which represent the buffer in little endian format.
|
||||
|
||||
=item B<-sign>
|
||||
|
||||
Sign the input data (which must be a hash) and output the signed result. This
|
||||
requires a private key.
|
||||
|
||||
=item B<-verify>
|
||||
|
||||
Verify the input data (which must be a hash) against the signature file and
|
||||
indicate if the verification succeeded or failed.
|
||||
|
||||
=item B<-verifyrecover>
|
||||
|
||||
Verify the input data (which must be a hash) and output the recovered data.
|
||||
|
||||
=item B<-encrypt>
|
||||
|
||||
Encrypt the input data using a public key.
|
||||
|
||||
=item B<-decrypt>
|
||||
|
||||
Decrypt the input data using a private key.
|
||||
|
||||
=item B<-derive>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-asn1parse>
|
||||
|
||||
Parse the ASN.1 output data, this is useful when combined with the
|
||||
B<-verifyrecover> option when an ASN1 structure is signed.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=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.
|
||||
|
||||
Unless otherwise mentioned all algorithms support the B<digest:alg> option
|
||||
which specifies the digest in use for sign, verify and verifyrecover operations.
|
||||
The value B<alg> should represent a digest name as used in the
|
||||
EVP_get_digestbyname() function for example B<sha1>. This value is not used to
|
||||
hash the input data. It is used (by some algorithms) for sanity-checking the
|
||||
lengths of data passed in to the B<pkeyutl> and for creating the structures that
|
||||
make up the signature (e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
|
||||
|
||||
This utility does not hash the input data but rather it will use the data
|
||||
directly as input to the signature algorithm. Depending on the key type,
|
||||
signature type, and mode of padding, the maximum acceptable lengths of input
|
||||
data differ. The signed data can't be longer than the key modulus with RSA. In
|
||||
case of ECDSA and DSA the data shouldn't be longer than the field
|
||||
size, otherwise it will be silently truncated to the field size. In any event
|
||||
the input size must not be larger than the largest supported digest size.
|
||||
|
||||
In other words, if the value of digest is B<sha1> the input should be the 20
|
||||
bytes long binary encoding of the SHA-1 hash function output.
|
||||
|
||||
The Ed25519 and Ed448 signature algorithms are not supported by this utility.
|
||||
They accept non-hashed input, but this utility can only be used to sign hashed
|
||||
input.
|
||||
|
||||
=head1 RSA ALGORITHM
|
||||
|
||||
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>
|
||||
|
||||
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
|
||||
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<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,
|
||||
verify and verifyrecover are can be performed in this mode.
|
||||
|
||||
For B<pss> mode only sign and verify are supported and the digest type must be
|
||||
specified.
|
||||
|
||||
=item B<rsa_pss_saltlen:len>
|
||||
|
||||
For B<pss> mode only this option specifies the salt length. Three special
|
||||
values are supported: "digest" sets the salt length to the digest length,
|
||||
"max" sets the salt length to the maximum permissible value. When verifying
|
||||
"auto" causes the salt length to be automatically determined based on the
|
||||
B<PSS> block structure.
|
||||
|
||||
=item B<rsa_mgf1_md:digest>
|
||||
|
||||
For PSS and OAEP padding sets the MGF1 digest. If the MGF1 digest is not
|
||||
explicitly set in PSS mode then the signing digest is used.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RSA-PSS ALGORITHM
|
||||
|
||||
The RSA-PSS algorithm is a restricted version of the RSA algorithm which only
|
||||
supports the sign and verify operations with PSS padding. The following
|
||||
additional B<pkeyopt> values are supported:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<rsa_padding_mode:mode>, B<rsa_pss_saltlen:len>, B<rsa_mgf1_md:digest>
|
||||
|
||||
These have the same meaning as the B<RSA> algorithm with some additional
|
||||
restrictions. The padding mode can only be set to B<pss> which is the
|
||||
default value.
|
||||
|
||||
If the key has parameter restrictions than the digest, MGF1
|
||||
digest and salt length are set to the values specified in the parameters.
|
||||
The digest and MG cannot be changed and the salt length cannot be set to a
|
||||
value less than the minimum restriction.
|
||||
|
||||
=back
|
||||
|
||||
=head1 DSA ALGORITHM
|
||||
|
||||
The DSA algorithm supports signing and verification operations only. Currently
|
||||
there are no additional B<-pkeyopt> options other than B<digest>. The SHA1
|
||||
digest is assumed by default.
|
||||
|
||||
=head1 DH ALGORITHM
|
||||
|
||||
The DH algorithm only supports the derivation operation and no additional
|
||||
B<-pkeyopt> options.
|
||||
|
||||
=head1 EC ALGORITHM
|
||||
|
||||
The EC algorithm supports sign, verify and derive operations. The sign and
|
||||
verify operations use ECDSA and derive uses ECDH. SHA1 is assumed by default for
|
||||
the B<-pkeyopt> B<digest> option.
|
||||
|
||||
=head1 X25519 and X448 ALGORITHMS
|
||||
|
||||
The X25519 and X448 algorithms support 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
|
||||
|
||||
Recover the signed data (e.g. if an RSA key is used):
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
Derive a shared secret value:
|
||||
|
||||
openssl 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:
|
||||
|
||||
openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
|
||||
-pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
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-2021 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
|
||||
@@ -0,0 +1,68 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-prime,
|
||||
prime - compute prime numbers
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl prime>
|
||||
[B<-help>]
|
||||
[B<-hex>]
|
||||
[B<-generate>]
|
||||
[B<-bits>]
|
||||
[B<-safe>]
|
||||
[B<-checks>]
|
||||
[I<number...>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<prime> command checks if the specified numbers are prime.
|
||||
|
||||
If no numbers are given on the command line, the B<-generate> flag should
|
||||
be used to generate primes according to the requirements specified by the
|
||||
rest of the flags.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item [B<-help>]
|
||||
|
||||
Display an option summary.
|
||||
|
||||
=item [B<-hex>]
|
||||
|
||||
Generate hex output.
|
||||
|
||||
=item [B<-generate>]
|
||||
|
||||
Generate a prime number.
|
||||
|
||||
=item [B<-bits num>]
|
||||
|
||||
Generate a prime with B<num> bits.
|
||||
|
||||
=item [B<-safe>]
|
||||
|
||||
When used with B<-generate>, generates a "safe" prime. If the number
|
||||
generated is B<n>, then check that B<(n-1)/2> is also prime.
|
||||
|
||||
=item [B<-checks num>]
|
||||
|
||||
Perform the checks B<num> times to see that the generated number
|
||||
is prime. The default is 20.
|
||||
|
||||
=back
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 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
|
||||
@@ -0,0 +1,95 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-rand,
|
||||
rand - generate pseudo-random bytes
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl rand>
|
||||
[B<-help>]
|
||||
[B<-out> I<file>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-base64>]
|
||||
[B<-hex>]
|
||||
I<num>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This command generates I<num> random bytes using a cryptographically
|
||||
secure pseudo random number generator (CSPRNG).
|
||||
|
||||
The random bytes are generated using the L<RAND_bytes(3)> function,
|
||||
which provides a security level of 256 bits, provided it managed to
|
||||
seed itself successfully from a trusted operating system entropy source.
|
||||
Otherwise, the command will fail with a nonzero error code.
|
||||
For more details, see L<RAND_bytes(3)>, L<RAND(7)>, and L<RAND_DRBG(7)>.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Print out a usage message.
|
||||
|
||||
=item B<-out file>
|
||||
|
||||
Write to I<file> instead of standard output.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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.
|
||||
Explicitly specifying a seed file is in general not necessary, see the
|
||||
L</NOTES> section for more information.
|
||||
|
||||
=item [B<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-base64>
|
||||
|
||||
Perform base64 encoding on the output.
|
||||
|
||||
=item B<-hex>
|
||||
|
||||
Show the output as a hex string.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Prior to OpenSSL 1.1.1, it was common for applications to store information
|
||||
about the state of the random-number generator in a file that was loaded
|
||||
at startup and rewritten upon exit. On modern operating systems, this is
|
||||
generally no longer necessary as OpenSSL will seed itself from a trusted
|
||||
entropy source provided by the operating system. The B<-rand> and
|
||||
B<-writerand> flags are still supported for special platforms or
|
||||
circumstances that might require them.
|
||||
|
||||
It is generally an error to use the same seed file more than once and
|
||||
every use of B<-rand> should be paired with B<-writerand>.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<RAND_bytes(3)>,
|
||||
L<RAND(7)>,
|
||||
L<RAND_DRBG(7)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,146 @@
|
||||
=pod
|
||||
|
||||
=for comment
|
||||
Original text by James Westby, contributed under the OpenSSL license.
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-c_rehash, openssl-rehash,
|
||||
c_rehash, rehash - Create symbolic links to files named by the hash values
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl>
|
||||
B<rehash>
|
||||
B<[-h]>
|
||||
B<[-help]>
|
||||
B<[-old]>
|
||||
B<[-n]>
|
||||
B<[-v]>
|
||||
[ I<directory>...]
|
||||
|
||||
B<c_rehash>
|
||||
I<flags...>
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
On some platforms, the OpenSSL B<rehash> command is available as
|
||||
an external script called B<c_rehash>. They are functionally equivalent,
|
||||
except for minor differences noted below.
|
||||
|
||||
B<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 should 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 an error will be generated.
|
||||
|
||||
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<rehash> will first remove all links
|
||||
that have a name in that syntax, even if they are being used for some
|
||||
other purpose.
|
||||
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 or if
|
||||
more than one such object appears in the file.
|
||||
|
||||
=head2 Script Configuration
|
||||
|
||||
The B<c_rehash> script
|
||||
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<-help> B<-h>
|
||||
|
||||
Display a brief usage message.
|
||||
|
||||
=item B<-old>
|
||||
|
||||
Use old-style hashing (MD5, as opposed to SHA-1) for generating
|
||||
links to be used for releases before 1.0.0.
|
||||
Note that current versions will not use the old style.
|
||||
|
||||
=item B<-n>
|
||||
|
||||
Do not remove existing links.
|
||||
This is needed when keeping new and old-style links in the same directory.
|
||||
|
||||
=item B<-compat>
|
||||
|
||||
Generate links for both old-style (MD5) and new-style (SHA1) hashing.
|
||||
This allows releases before 1.0.0 to use these links along-side newer
|
||||
releases.
|
||||
|
||||
=item B<-v>
|
||||
|
||||
Print messages about old links removed and new links created.
|
||||
By default, B<rehash> only lists each directory as it is processed.
|
||||
|
||||
=back
|
||||
|
||||
=head1 ENVIRONMENT
|
||||
|
||||
=over 4
|
||||
|
||||
=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)>,
|
||||
L<crl(1)>.
|
||||
L<x509(1)>.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2015-2018 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
|
||||
@@ -0,0 +1,705 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-req,
|
||||
req - PKCS#10 certificate request and certificate generating utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<req>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-passin arg>]
|
||||
[B<-out filename>]
|
||||
[B<-passout arg>]
|
||||
[B<-text>]
|
||||
[B<-pubkey>]
|
||||
[B<-noout>]
|
||||
[B<-verify>]
|
||||
[B<-modulus>]
|
||||
[B<-new>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-newkey rsa:bits>]
|
||||
[B<-newkey alg:file>]
|
||||
[B<-nodes>]
|
||||
[B<-key filename>]
|
||||
[B<-keyform PEM|DER>]
|
||||
[B<-keyout filename>]
|
||||
[B<-keygen_engine id>]
|
||||
[B<-I<digest>>]
|
||||
[B<-config filename>]
|
||||
[B<-multivalue-rdn>]
|
||||
[B<-x509>]
|
||||
[B<-days n>]
|
||||
[B<-set_serial n>]
|
||||
[B<-newhdr>]
|
||||
[B<-addext ext>]
|
||||
[B<-extensions section>]
|
||||
[B<-reqexts section>]
|
||||
[B<-precert>]
|
||||
[B<-utf8>]
|
||||
[B<-nameopt>]
|
||||
[B<-reqopt>]
|
||||
[B<-subject>]
|
||||
[B<-subj arg>]
|
||||
[B<-sigopt nm:v>]
|
||||
[B<-batch>]
|
||||
[B<-verbose>]
|
||||
[B<-engine id>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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 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
|
||||
form compatible with the PKCS#10. 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>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
This specifies the input filename to read a request from or standard input
|
||||
if this option is not specified. A request is only read if the creation
|
||||
options (B<-new> and B<-newkey>) are not specified.
|
||||
|
||||
=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 input file password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write to or standard output by
|
||||
default.
|
||||
|
||||
=item B<-passout arg>
|
||||
|
||||
The output file password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
Prints out the certificate request in text form.
|
||||
|
||||
=item B<-subject>
|
||||
|
||||
Prints out the request subject (or certificate subject if B<-x509> is
|
||||
specified)
|
||||
|
||||
=item B<-pubkey>
|
||||
|
||||
Outputs the public key.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
This option prevents output of the encoded version of the request.
|
||||
|
||||
=item B<-modulus>
|
||||
|
||||
This option prints out the value of the modulus of the public key
|
||||
contained in the request.
|
||||
|
||||
=item B<-verify>
|
||||
|
||||
Verifies the signature on the request.
|
||||
|
||||
=item B<-new>
|
||||
|
||||
This option generates a new certificate request. It will prompt
|
||||
the user for the relevant field values. The actual fields
|
||||
prompted for and their maximum and minimum sizes are specified
|
||||
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<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-newkey arg>
|
||||
|
||||
This option creates a new certificate request and a new private
|
||||
key. The argument takes one of several forms. B<rsa:nbits>, where
|
||||
B<nbits> is the number of bits, generates an RSA key B<nbits>
|
||||
in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified,
|
||||
the default key size, specified in the configuration file is used.
|
||||
|
||||
All other algorithms support the B<-newkey alg:file> form, where file may be
|
||||
an algorithm parameter file, created by the B<genpkey -genparam> command
|
||||
or and X.509 certificate for a key with 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 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
|
||||
ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R
|
||||
34.10-2001 key (requires B<ccgost> engine configured in the configuration
|
||||
file). If just B<gost2001> is specified a parameter set should be
|
||||
specified by B<-pkeyopt paramset:X>
|
||||
|
||||
|
||||
=item B<-pkeyopt opt:value>
|
||||
|
||||
Set the public key algorithm option B<opt> to B<value>. The precise set of
|
||||
options supported depends on the public key algorithm used and its
|
||||
implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page
|
||||
for more details.
|
||||
|
||||
=item B<-key filename>
|
||||
|
||||
This specifies the file to read the private key from. It also
|
||||
accepts PKCS#8 format private keys for PEM format files.
|
||||
|
||||
=item B<-keyform PEM|DER>
|
||||
|
||||
The format of the private key file specified in the B<-key>
|
||||
argument. PEM is the default.
|
||||
|
||||
=item B<-keyout filename>
|
||||
|
||||
This gives the filename to write the newly created private key to.
|
||||
If this option is not specified then the filename present in the
|
||||
configuration file is used.
|
||||
|
||||
=item B<-nodes>
|
||||
|
||||
If this option is specified then if a private key is created it
|
||||
will not be encrypted.
|
||||
|
||||
=item B<-I<digest>>
|
||||
|
||||
This specifies the message digest to sign the request.
|
||||
Any digest supported by the OpenSSL 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
|
||||
signatures always use SHA1, GOST R 34.10 signatures always use
|
||||
GOST R 34.11-94 (B<-md_gost94>), Ed25519 and Ed448 never use any digest.
|
||||
|
||||
=item B<-config filename>
|
||||
|
||||
This allows an alternative configuration file to be specified.
|
||||
Optional; for a description of the default value,
|
||||
see L<openssl(1)/COMMAND SUMMARY>.
|
||||
|
||||
=item B<-subj arg>
|
||||
|
||||
Sets subject name for new request or supersedes the subject name
|
||||
when processing a request.
|
||||
The arg must be formatted as I</type0=value0/type1=value1/type2=...>.
|
||||
Keyword characters may be escaped by \ (backslash), and whitespace is retained.
|
||||
Empty values are permitted, but the corresponding type will not be included
|
||||
in the request.
|
||||
|
||||
=item B<-multivalue-rdn>
|
||||
|
||||
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>
|
||||
|
||||
If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
|
||||
|
||||
=item B<-x509>
|
||||
|
||||
This option outputs a self signed certificate instead of a certificate
|
||||
request. This is typically used to generate a test certificate or
|
||||
a self signed root CA. The extensions added to the certificate
|
||||
(if any) are specified in the configuration file. Unless specified
|
||||
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
|
||||
days to certify the certificate for, otherwise it is ignored. B<n> should
|
||||
be a positive integer. The default is 30 days.
|
||||
|
||||
=item B<-set_serial n>
|
||||
|
||||
Serial number to use when outputting a self signed certificate. This
|
||||
may be specified as a decimal value or a hex value if preceded by B<0x>.
|
||||
|
||||
=item B<-addext ext>
|
||||
|
||||
Add a specific extension to the certificate (if the B<-x509> option is
|
||||
present) or certificate request. The argument must have the form of
|
||||
a key=value pair as it would appear in a config file.
|
||||
|
||||
This option can be given multiple times.
|
||||
|
||||
=item B<-extensions section>
|
||||
|
||||
=item B<-reqexts section>
|
||||
|
||||
These options specify alternative sections to include certificate
|
||||
extensions (if the B<-x509> option is present) or certificate
|
||||
request extensions. This allows several different sections to
|
||||
be used in the same configuration file to specify requests for
|
||||
a variety of purposes.
|
||||
|
||||
=item B<-precert>
|
||||
|
||||
A poison extension will be added to the certificate, making it a
|
||||
"pre-certificate" (see RFC6962). This can be submitted to Certificate
|
||||
Transparency logs in order to obtain signed certificate timestamps (SCTs).
|
||||
These SCTs can then be embedded into the pre-certificate as an extension, before
|
||||
removing the poison and signing the certificate.
|
||||
|
||||
This implies the B<-new> flag.
|
||||
|
||||
=item B<-utf8>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-nameopt option>
|
||||
|
||||
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)> manual page for details.
|
||||
|
||||
=item B<-reqopt>
|
||||
|
||||
Customise the output format used with B<-text>. The B<option> argument can be
|
||||
a single option or multiple options separated by commas.
|
||||
|
||||
See discussion of the B<-certopt> parameter in the L<x509(1)>
|
||||
command.
|
||||
|
||||
=item B<-newhdr>
|
||||
|
||||
Adds the word B<NEW> to the PEM file header and footer lines on the outputted
|
||||
request. Some software (Netscape certificate server) and some CAs need this.
|
||||
|
||||
=item B<-batch>
|
||||
|
||||
Non-interactive mode.
|
||||
|
||||
=item B<-verbose>
|
||||
|
||||
Print extra details about the operations being performed.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<req>
|
||||
to attempt to obtain a functional reference to the specified engine,
|
||||
thus initialising it if needed. The engine will then be set as the default
|
||||
for all available algorithms.
|
||||
|
||||
=item B<-keygen_engine id>
|
||||
|
||||
Specifies an engine (by its unique B<id> string) which would be used
|
||||
for key generation operations.
|
||||
|
||||
=back
|
||||
|
||||
=head1 CONFIGURATION FILE FORMAT
|
||||
|
||||
The configuration options are specified in the B<req> section of
|
||||
the configuration file. As with all configuration files if no
|
||||
value is specified in the specific section (i.e. B<req>) then
|
||||
the initial unnamed or B<default> section is searched too.
|
||||
|
||||
The options available are described in detail below.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<input_password output_password>
|
||||
|
||||
The passwords for the input private key file (if present) and
|
||||
the output private key file (if one will be created). The
|
||||
command line options B<passin> and B<passout> override the
|
||||
configuration file values.
|
||||
|
||||
=item B<default_bits>
|
||||
|
||||
Specifies the default key size in bits.
|
||||
|
||||
This option is used in conjunction with the B<-new> option to generate
|
||||
a new key. It can be overridden by specifying an explicit key size in
|
||||
the B<-newkey> option. The smallest accepted key size is 512 bits. If
|
||||
no key size is specified then 2048 bits is used.
|
||||
|
||||
=item B<default_keyfile>
|
||||
|
||||
This is the default filename to write a private key to. If not
|
||||
specified the key is written to standard output. This can be
|
||||
overridden by the B<-keyout> option.
|
||||
|
||||
=item B<oid_file>
|
||||
|
||||
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.
|
||||
|
||||
=item B<oid_section>
|
||||
|
||||
This specifies a section in the configuration file containing extra
|
||||
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<RANDFILE>
|
||||
|
||||
At startup the specified file is loaded into the random number generator,
|
||||
and at exit 256 bytes will be written to it.
|
||||
It is used for private key generation.
|
||||
|
||||
=item B<encrypt_key>
|
||||
|
||||
If this is set to B<no> then if a private key is generated it is
|
||||
B<not> encrypted. This is equivalent to the B<-nodes> command line
|
||||
option. For compatibility B<encrypt_rsa_key> is an equivalent option.
|
||||
|
||||
=item B<default_md>
|
||||
|
||||
This option specifies the digest algorithm to use. Any digest supported by the
|
||||
OpenSSL B<dgst> command can be used. This option can be overridden on the
|
||||
command line. Certain signing algorithms (i.e. Ed25519 and Ed448) will ignore
|
||||
any digest that has been set.
|
||||
|
||||
=item B<string_mask>
|
||||
|
||||
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
|
||||
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
|
||||
is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
|
||||
option just uses PrintableStrings and T61Strings: certain software has
|
||||
problems with BMPStrings and UTF8Strings: in particular Netscape.
|
||||
|
||||
=item B<req_extensions>
|
||||
|
||||
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)> manual page for details of the
|
||||
extension section format.
|
||||
|
||||
=item B<x509_extensions>
|
||||
|
||||
This specifies the configuration file section containing a list of
|
||||
extensions to add to certificate generated when the B<-x509> switch
|
||||
is used. It can be overridden by the B<-extensions> command line switch.
|
||||
|
||||
=item B<prompt>
|
||||
|
||||
If set to the value B<no> this disables prompting of certificate fields
|
||||
and just takes values from the config file directly. It also changes the
|
||||
expected format of the B<distinguished_name> and B<attributes> sections.
|
||||
|
||||
=item B<utf8>
|
||||
|
||||
If set to the value B<yes> then 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.
|
||||
|
||||
=item B<attributes>
|
||||
|
||||
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.
|
||||
|
||||
=item B<distinguished_name>
|
||||
|
||||
This specifies the section containing the distinguished name fields to
|
||||
prompt for when generating a certificate or certificate request. The format
|
||||
is described in the next section.
|
||||
|
||||
=back
|
||||
|
||||
=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
|
||||
|
||||
There are two separate formats for the distinguished name and attribute
|
||||
sections. If the B<prompt> option is set to B<no> then these sections
|
||||
just consist of field names and values: for example,
|
||||
|
||||
CN=My Name
|
||||
OU=My Organization
|
||||
emailAddress=someone@somewhere.org
|
||||
|
||||
This allows external programs (e.g. GUI based) to generate a template file
|
||||
with all the field names and values and just pass it to B<req>. An example
|
||||
of this kind of configuration file is contained in the B<EXAMPLES> section.
|
||||
|
||||
Alternatively if the B<prompt> option is absent or not set to B<no> then the
|
||||
file contains field prompting information. It consists of lines of the form:
|
||||
|
||||
fieldName="prompt"
|
||||
fieldName_default="default field value"
|
||||
fieldName_min= 2
|
||||
fieldName_max= 4
|
||||
|
||||
"fieldName" is the field name being used, for example commonName (or CN).
|
||||
The "prompt" string is used to ask the user to enter the relevant
|
||||
details. If the user enters nothing then the default value is used if no
|
||||
default value is present then the field is omitted. A field can
|
||||
still be omitted if a default value is present if the user just
|
||||
enters the '.' character.
|
||||
|
||||
The number of characters entered must be between the fieldName_min and
|
||||
fieldName_max limits: there may be additional restrictions based
|
||||
on the field being used (for example countryName can only ever be
|
||||
two characters long and must fit in a PrintableString).
|
||||
|
||||
Some fields (such as organizationName) can be used more than once
|
||||
in a DN. This presents a problem because configuration files will
|
||||
not recognize the same name occurring twice. To avoid this problem
|
||||
if the fieldName contains some characters followed by a full stop
|
||||
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
|
||||
values such as commonName, countryName, localityName, organizationName,
|
||||
organizationalUnitName, stateOrProvinceName. Additionally emailAddress
|
||||
is included as well as name, surname, givenName, initials, and dnQualifier.
|
||||
|
||||
Additional object identifiers can be defined with the B<oid_file> or
|
||||
B<oid_section> options in the configuration file. Any additional fields
|
||||
will be treated as though they were a DirectoryString.
|
||||
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Examine and verify certificate request:
|
||||
|
||||
openssl 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
|
||||
|
||||
The same but just using req:
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
Example of a section pointed to by B<oid_section> making use of variable
|
||||
expansion:
|
||||
|
||||
testoid1=1.2.3.5
|
||||
testoid2=${testoid1}.6
|
||||
|
||||
Sample configuration file prompting for field values:
|
||||
|
||||
[ req ]
|
||||
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
|
||||
|
||||
localityName = Locality Name (eg, city)
|
||||
|
||||
organizationalUnitName = Organizational Unit Name (eg, section)
|
||||
|
||||
commonName = Common Name (eg, YOUR name)
|
||||
commonName_max = 64
|
||||
|
||||
emailAddress = Email Address
|
||||
emailAddress_max = 40
|
||||
|
||||
[ req_attributes ]
|
||||
challengePassword = A challenge password
|
||||
challengePassword_min = 4
|
||||
challengePassword_max = 20
|
||||
|
||||
[ v3_ca ]
|
||||
|
||||
subjectKeyIdentifier=hash
|
||||
authorityKeyIdentifier=keyid:always,issuer:always
|
||||
basicConstraints = critical, CA:true
|
||||
|
||||
Sample configuration containing all field values:
|
||||
|
||||
|
||||
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
|
||||
|
||||
[ 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
|
||||
|
||||
[ req_attributes ]
|
||||
challengePassword = A challenge password
|
||||
|
||||
Example of giving the most common attributes (subject and extensions)
|
||||
on the command line:
|
||||
|
||||
openssl req -new -subj "/C=GB/CN=foo" \
|
||||
-addext "subjectAltName = DNS:foo.co.uk" \
|
||||
-addext "certificatePolicies = 1.2.3.4" \
|
||||
-newkey rsa:2048 -keyout key.pem -out req.pem
|
||||
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The header and footer lines in the B<PEM> format are normally:
|
||||
|
||||
-----BEGIN CERTIFICATE REQUEST-----
|
||||
-----END CERTIFICATE REQUEST-----
|
||||
|
||||
some software (some versions of Netscape certificate server) instead needs:
|
||||
|
||||
-----BEGIN NEW CERTIFICATE REQUEST-----
|
||||
-----END NEW CERTIFICATE REQUEST-----
|
||||
|
||||
which is produced with the B<-newhdr> option but is otherwise compatible.
|
||||
Either form is accepted transparently on input.
|
||||
|
||||
The certificate requests generated by B<Xenroll> with MSIE have extensions
|
||||
added. It includes the B<keyUsage> extension which determines the type of
|
||||
key (signature only or general purpose) and any additional OIDs entered
|
||||
by the script in an extendedKeyUsage extension.
|
||||
|
||||
=head1 DIAGNOSTICS
|
||||
|
||||
The following messages are frequently asked about:
|
||||
|
||||
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
|
||||
|
||||
The first error message is the clue: it can't find the configuration
|
||||
file! Certain operations (like examining a certificate request) don't
|
||||
need a configuration file so its use isn't enforced. Generation of
|
||||
certificates or requests however does need a configuration file. This
|
||||
could be regarded as a bug.
|
||||
|
||||
Another puzzling message is this:
|
||||
|
||||
Attributes:
|
||||
a0:00
|
||||
|
||||
this is displayed when no attributes are present and the request includes
|
||||
the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
|
||||
0x00). If you just see:
|
||||
|
||||
Attributes:
|
||||
|
||||
then the B<SET OF> is missing and the encoding is technically invalid (but
|
||||
it is tolerated). See the description of the command line option B<-asn1-kludge>
|
||||
for more information.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
OpenSSL'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
|
||||
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.
|
||||
|
||||
The current prompting is not very friendly. It doesn't allow you to confirm what
|
||||
you've just entered. Other things like extensions in certificate requests are
|
||||
statically defined in the configuration file. Some of these: like an email
|
||||
address in subjectAltName should be input by the user.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
|
||||
L<gendsa(1)>, L<config(5)>,
|
||||
L<x509v3_config(5)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,205 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-rsa,
|
||||
rsa - RSA key processing tool
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<rsa>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER>]
|
||||
[B<-in filename>]
|
||||
[B<-passin arg>]
|
||||
[B<-out filename>]
|
||||
[B<-passout arg>]
|
||||
[B<-aes128>]
|
||||
[B<-aes192>]
|
||||
[B<-aes256>]
|
||||
[B<-aria128>]
|
||||
[B<-aria192>]
|
||||
[B<-aria256>]
|
||||
[B<-camellia128>]
|
||||
[B<-camellia192>]
|
||||
[B<-camellia256>]
|
||||
[B<-des>]
|
||||
[B<-des3>]
|
||||
[B<-idea>]
|
||||
[B<-text>]
|
||||
[B<-noout>]
|
||||
[B<-modulus>]
|
||||
[B<-check>]
|
||||
[B<-pubin>]
|
||||
[B<-pubout>]
|
||||
[B<-RSAPublicKey_in>]
|
||||
[B<-RSAPublicKey_out>]
|
||||
[B<-engine id>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<rsa> command processes RSA keys. They can be converted between various
|
||||
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>
|
||||
utility.
|
||||
|
||||
=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
|
||||
form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format.
|
||||
The B<PEM> form is the default format: it consists of the B<DER> format base64
|
||||
encoded with additional header and footer lines. On input PKCS#8 format private
|
||||
keys are also accepted.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write a key to or standard output if this
|
||||
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 L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-aes128>, B<-aes192>, B<-aes256>, B<-aria128>, B<-aria192>, B<-aria256>, B<-camellia128>, B<-camellia192>, B<-camellia256>, B<-des>, B<-des3>, B<-idea>
|
||||
|
||||
These options encrypt the private key with the specified
|
||||
cipher 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<rsa> utility to read in an encrypted key with no
|
||||
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.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
Prints out the various public or private key components in
|
||||
plain text in addition to the encoded version.
|
||||
|
||||
=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 modulus of the key.
|
||||
|
||||
=item B<-check>
|
||||
|
||||
This option checks the consistency of an RSA private 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<-RSAPublicKey_in>, B<-RSAPublicKey_out>
|
||||
|
||||
Like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<rsa>
|
||||
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
|
||||
|
||||
The PEM private key format uses the header and footer lines:
|
||||
|
||||
-----BEGIN RSA PRIVATE KEY-----
|
||||
-----END RSA PRIVATE KEY-----
|
||||
|
||||
The PEM public key format uses the header and footer lines:
|
||||
|
||||
-----BEGIN PUBLIC KEY-----
|
||||
-----END PUBLIC KEY-----
|
||||
|
||||
The PEM B<RSAPublicKey> format uses the header and footer lines:
|
||||
|
||||
-----BEGIN RSA PUBLIC KEY-----
|
||||
-----END RSA PUBLIC KEY-----
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
To remove the pass phrase on an RSA private key:
|
||||
|
||||
openssl rsa -in key.pem -out keyout.pem
|
||||
|
||||
To encrypt a private key using triple DES:
|
||||
|
||||
openssl rsa -in key.pem -des3 -out keyout.pem
|
||||
|
||||
To convert a private key from PEM to DER format:
|
||||
|
||||
openssl 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
|
||||
|
||||
To just output the public part of a private key:
|
||||
|
||||
openssl 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
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
There should be an option that automatically handles .key files,
|
||||
without having to manually edit them.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<pkcs8(1)>, L<dsa(1)>, L<genrsa(1)>,
|
||||
L<gendsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,220 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-rsautl,
|
||||
rsautl - RSA utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<rsautl>
|
||||
[B<-help>]
|
||||
[B<-in file>]
|
||||
[B<-out file>]
|
||||
[B<-inkey file>]
|
||||
[B<-keyform PEM|DER|ENGINE>]
|
||||
[B<-pubin>]
|
||||
[B<-certin>]
|
||||
[B<-sign>]
|
||||
[B<-verify>]
|
||||
[B<-encrypt>]
|
||||
[B<-decrypt>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-pkcs>]
|
||||
[B<-ssl>]
|
||||
[B<-raw>]
|
||||
[B<-hexdump>]
|
||||
[B<-asn1parse>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<rsautl> command can be used to sign, verify, encrypt and decrypt
|
||||
data using the RSA algorithm.
|
||||
|
||||
=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
|
||||
if this option is not specified.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
Specifies the output filename to write to or standard output by
|
||||
default.
|
||||
|
||||
=item B<-inkey file>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-certin>
|
||||
|
||||
The input is a certificate containing an RSA public key.
|
||||
|
||||
=item B<-sign>
|
||||
|
||||
Sign the input data and output the signed result. This requires
|
||||
an RSA private key.
|
||||
|
||||
=item B<-verify>
|
||||
|
||||
Verify the input data and output the recovered data.
|
||||
|
||||
=item B<-encrypt>
|
||||
|
||||
Encrypt the input data using an RSA public key.
|
||||
|
||||
=item B<-decrypt>
|
||||
|
||||
Decrypt the input data using an RSA private key.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-pkcs, -oaep, -ssl, -raw>
|
||||
|
||||
The padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
|
||||
special padding used in SSL v2 backwards compatible handshakes,
|
||||
or no padding, respectively.
|
||||
For signatures, only B<-pkcs> and B<-raw> can be used.
|
||||
|
||||
=item B<-hexdump>
|
||||
|
||||
Hex dump the output data.
|
||||
|
||||
=item B<-asn1parse>
|
||||
|
||||
Parse the ASN.1 output data, this is useful when combined with the
|
||||
B<-verify> option.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
B<rsautl> because it uses the RSA algorithm directly can only be
|
||||
used to sign or verify small pieces of data.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Sign some data using a private key:
|
||||
|
||||
openssl rsautl -sign -in file -inkey key.pem -out sig
|
||||
|
||||
Recover the signed data
|
||||
|
||||
openssl rsautl -verify -in sig -inkey key.pem
|
||||
|
||||
Examine the raw signed data:
|
||||
|
||||
openssl rsautl -verify -in sig -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 ................
|
||||
0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
|
||||
0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
|
||||
0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
|
||||
0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
|
||||
0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
|
||||
0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world
|
||||
|
||||
The PKCS#1 block formatting is evident from this. If this was done using
|
||||
encrypt and decrypt the block would have been of type 2 (the second byte)
|
||||
and random padding data visible instead of the 0xff bytes.
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
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
|
||||
|
||||
|
||||
The final BIT STRING contains the actual signature. It can be extracted with:
|
||||
|
||||
openssl 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
|
||||
|
||||
The signature can be analysed with:
|
||||
|
||||
openssl 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
|
||||
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
|
||||
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
|
||||
|
||||
and its digest computed with:
|
||||
|
||||
openssl 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)>, L<rsa(1)>, L<genrsa(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 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
|
||||
@@ -0,0 +1,838 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-s_client,
|
||||
s_client - SSL/TLS client program
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<s_client>
|
||||
[B<-help>]
|
||||
[B<-connect host:port>]
|
||||
[B<-bind host:port>]
|
||||
[B<-proxy host:port>]
|
||||
[B<-unix path>]
|
||||
[B<-4>]
|
||||
[B<-6>]
|
||||
[B<-servername name>]
|
||||
[B<-noservername>]
|
||||
[B<-verify depth>]
|
||||
[B<-verify_return_error>]
|
||||
[B<-cert filename>]
|
||||
[B<-certform DER|PEM>]
|
||||
[B<-key filename>]
|
||||
[B<-keyform DER|PEM>]
|
||||
[B<-cert_chain filename>]
|
||||
[B<-build_chain>]
|
||||
[B<-xkey>]
|
||||
[B<-xcert>]
|
||||
[B<-xchain>]
|
||||
[B<-xchain_build>]
|
||||
[B<-xcertform PEM|DER>]
|
||||
[B<-xkeyform PEM|DER>]
|
||||
[B<-pass arg>]
|
||||
[B<-CApath directory>]
|
||||
[B<-CAfile filename>]
|
||||
[B<-chainCApath directory>]
|
||||
[B<-chainCAfile filename>]
|
||||
[B<-no-CAfile>]
|
||||
[B<-no-CApath>]
|
||||
[B<-requestCAfile filename>]
|
||||
[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<-nameopt option>]
|
||||
[B<-verify_depth num>]
|
||||
[B<-verify_email email>]
|
||||
[B<-verify_hostname hostname>]
|
||||
[B<-verify_ip ip>]
|
||||
[B<-verify_name name>]
|
||||
[B<-build_chain>]
|
||||
[B<-x509_strict>]
|
||||
[B<-reconnect>]
|
||||
[B<-showcerts>]
|
||||
[B<-debug>]
|
||||
[B<-msg>]
|
||||
[B<-nbio_test>]
|
||||
[B<-state>]
|
||||
[B<-nbio>]
|
||||
[B<-crlf>]
|
||||
[B<-ign_eof>]
|
||||
[B<-no_ign_eof>]
|
||||
[B<-psk_identity identity>]
|
||||
[B<-psk key>]
|
||||
[B<-psk_session file>]
|
||||
[B<-quiet>]
|
||||
[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>]
|
||||
[B<-dtls>]
|
||||
[B<-dtls1>]
|
||||
[B<-dtls1_2>]
|
||||
[B<-sctp>]
|
||||
[B<-sctp_label_bug>]
|
||||
[B<-fallback_scsv>]
|
||||
[B<-async>]
|
||||
[B<-max_send_frag>]
|
||||
[B<-split_send_frag>]
|
||||
[B<-max_pipelines>]
|
||||
[B<-read_buf>]
|
||||
[B<-bugs>]
|
||||
[B<-comp>]
|
||||
[B<-no_comp>]
|
||||
[B<-allow_no_dhe_kex>]
|
||||
[B<-sigalgs sigalglist>]
|
||||
[B<-curves curvelist>]
|
||||
[B<-cipher cipherlist>]
|
||||
[B<-ciphersuites val>]
|
||||
[B<-serverpref>]
|
||||
[B<-starttls protocol>]
|
||||
[B<-xmpphost hostname>]
|
||||
[B<-name hostname>]
|
||||
[B<-engine id>]
|
||||
[B<-tlsextdebug>]
|
||||
[B<-no_ticket>]
|
||||
[B<-sess_out filename>]
|
||||
[B<-sess_in filename>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-serverinfo types>]
|
||||
[B<-status>]
|
||||
[B<-alpn protocols>]
|
||||
[B<-nextprotoneg protocols>]
|
||||
[B<-ct>]
|
||||
[B<-noct>]
|
||||
[B<-ctlogfile>]
|
||||
[B<-keylogfile file>]
|
||||
[B<-early_data file>]
|
||||
[B<-enable_pha>]
|
||||
[B<target>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
In addition to the options below the B<s_client> utility also supports the
|
||||
common and client only options documented
|
||||
in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
|
||||
manual page.
|
||||
|
||||
=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. It is possible to
|
||||
select the host and port using the optional target positional argument instead.
|
||||
If neither this nor the target positional argument are specified then an attempt
|
||||
is made to connect to the local host on port 4433.
|
||||
|
||||
=item B<-bind host:port>]
|
||||
|
||||
This specifies the host address and or port to bind as the source for the
|
||||
connection. For Unix-domain sockets the port is ignored and the host is
|
||||
used as the source socket address.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-unix path>
|
||||
|
||||
Connect over the specified Unix-domain socket.
|
||||
|
||||
=item B<-4>
|
||||
|
||||
Use IPv4 only.
|
||||
|
||||
=item B<-6>
|
||||
|
||||
Use IPv6 only.
|
||||
|
||||
=item B<-servername name>
|
||||
|
||||
Set the TLS SNI (Server Name Indication) extension in the ClientHello message to
|
||||
the given value.
|
||||
If B<-servername> is not provided, the TLS SNI extension will be populated with
|
||||
the name given to B<-connect> if it follows a DNS name format. If B<-connect> is
|
||||
not provided either, the SNI is set to "localhost".
|
||||
This is the default since OpenSSL 1.1.1.
|
||||
|
||||
Even though SNI should normally be a DNS name and not an IP address, if
|
||||
B<-servername> is provided then that name will be sent, regardless of whether
|
||||
it is a DNS name or not.
|
||||
|
||||
This option cannot be used in conjunction with B<-noservername>.
|
||||
|
||||
=item B<-noservername>
|
||||
|
||||
Suppresses sending of the SNI (Server Name Indication) extension in the
|
||||
ClientHello message. Cannot be used in conjunction with the B<-servername> or
|
||||
<-dane_tlsa_domain> options.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-cert_chain>
|
||||
|
||||
A file containing trusted certificates to use when attempting to build the
|
||||
client/server certificate chain related to the certificate specified via the
|
||||
B<-cert> option.
|
||||
|
||||
=item B<-build_chain>
|
||||
|
||||
Specify whether the application should build the certificate chain to be
|
||||
provided to the server.
|
||||
|
||||
=item B<-xkey infile>, B<-xcert infile>, B<-xchain>
|
||||
|
||||
Specify an extra certificate, private key and certificate chain. These behave
|
||||
in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When
|
||||
specified, the callback returning the first valid chain will be in use by the
|
||||
client.
|
||||
|
||||
=item B<-xchain_build>
|
||||
|
||||
Specify whether the application should build the certificate chain to be
|
||||
provided to the server for the extra certificates provided via B<-xkey infile>,
|
||||
B<-xcert infile>, B<-xchain> options.
|
||||
|
||||
=item B<-xcertform PEM|DER>, B<-xkeyform PEM|DER>
|
||||
|
||||
Extra certificate and private key format respectively.
|
||||
|
||||
=item B<-pass arg>
|
||||
|
||||
the private key password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-verify depth>
|
||||
|
||||
The verify depth to use. This specifies the maximum length of the
|
||||
server certificate chain and turns on server certificate verification.
|
||||
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<-nameopt option>
|
||||
|
||||
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)> manual page for details.
|
||||
|
||||
=item B<-CApath directory>
|
||||
|
||||
The directory to use for server certificate verification. This directory
|
||||
must be in "hash format", see L<verify(1)> 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<-chainCApath directory>
|
||||
|
||||
The directory to use for building the chain provided to the server. This
|
||||
directory must be in "hash format", see L<verify(1)> for more information.
|
||||
|
||||
=item B<-chainCAfile file>
|
||||
|
||||
A file containing trusted certificates 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<-requestCAfile file>
|
||||
|
||||
A file containing a list of certificates whose subject names will be sent
|
||||
to the server in the B<certificate_authorities> extension. Only supported
|
||||
for TLS 1.3
|
||||
|
||||
=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.
|
||||
|
||||
=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
|
||||
specified 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:
|
||||
|
||||
$ openssl 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.
|
||||
|
||||
=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<-showcerts>
|
||||
|
||||
Displays the server certificate list as sent by the server: it only consists of
|
||||
certificates the server has sent (in the order the server has sent them). It is
|
||||
B<not> a verified chain.
|
||||
|
||||
=item B<-prexit>
|
||||
|
||||
Print session information when the program exits. This will always attempt
|
||||
to print out information even if the connection fails. Normally information
|
||||
will only be printed out once if the connection succeeds. This option is useful
|
||||
because the cipher in use may be renegotiated or the connection may fail
|
||||
because a client certificate is required or is requested only after an
|
||||
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.
|
||||
|
||||
=item B<-state>
|
||||
|
||||
Prints out the SSL session states.
|
||||
|
||||
=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. OpenSSL needs to be compiled
|
||||
with B<enable-ssl-trace> for this option to work.
|
||||
|
||||
=item B<-msgfile>
|
||||
|
||||
File to send output of B<-msg> or B<-trace> to, default standard output.
|
||||
|
||||
=item B<-nbio_test>
|
||||
|
||||
Tests nonblocking I/O
|
||||
|
||||
=item B<-nbio>
|
||||
|
||||
Turns on nonblocking I/O
|
||||
|
||||
=item B<-crlf>
|
||||
|
||||
This option translated a line feed from the terminal into CR+LF as required
|
||||
by some servers.
|
||||
|
||||
=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.
|
||||
|
||||
=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>.
|
||||
|
||||
=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).
|
||||
|
||||
=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<-psk_session file>
|
||||
|
||||
Use the pem encoded SSL_SESSION data stored in B<file> as the basis of a PSK.
|
||||
Note that this will only work if TLSv1.3 is negotiated.
|
||||
|
||||
=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 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.
|
||||
Note that not all protocols and flags may be available, depending on how
|
||||
OpenSSL was built.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-sctp>
|
||||
|
||||
Use SCTP for the transport protocol instead of UDP in DTLS. Must be used in
|
||||
conjunction with B<-dtls>, B<-dtls1> or B<-dtls1_2>. This option is only
|
||||
available where OpenSSL has support for SCTP enabled.
|
||||
|
||||
=item B<-sctp_label_bug>
|
||||
|
||||
Use the incorrect behaviour of older OpenSSL implementations when computing
|
||||
endpoint-pair shared secrets for DTLS/SCTP. This allows communication with
|
||||
older broken implementations but breaks interoperability with correct
|
||||
implementations. Must be used in conjunction with B<-sctp>. This option is only
|
||||
available where OpenSSL has support for SCTP enabled.
|
||||
|
||||
=item B<-fallback_scsv>
|
||||
|
||||
Send TLS_FALLBACK_SCSV in the ClientHello.
|
||||
|
||||
=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).
|
||||
|
||||
=item B<-max_send_frag int>
|
||||
|
||||
The maximum size of data fragment to send.
|
||||
See L<SSL_CTX_set_max_send_fragment(3)> for further information.
|
||||
|
||||
=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 cipher suite 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.
|
||||
|
||||
=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 cipher suite has been negotiated. The default value is 1.
|
||||
See L<SSL_CTX_set_max_pipelines(3)> for further information.
|
||||
|
||||
=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).
|
||||
|
||||
=item B<-bugs>
|
||||
|
||||
There are several known bugs in SSL and TLS implementations. Adding this
|
||||
option enables various workarounds.
|
||||
|
||||
=item B<-comp>
|
||||
|
||||
Enables support for SSL/TLS compression.
|
||||
This option was introduced in OpenSSL 1.1.0.
|
||||
TLS compression is not recommended and is off by default as of
|
||||
OpenSSL 1.1.0.
|
||||
|
||||
=item B<-no_comp>
|
||||
|
||||
Disables support for SSL/TLS compression.
|
||||
TLS compression is not recommended and is off by default as of
|
||||
OpenSSL 1.1.0.
|
||||
|
||||
=item B<-brief>
|
||||
|
||||
Only provide a brief summary of connection parameters instead of the
|
||||
normal verbose output.
|
||||
|
||||
=item B<-sigalgs sigalglist>
|
||||
|
||||
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<-curves curvelist>
|
||||
|
||||
Specifies the list of supported curves to be sent by the client. The curve is
|
||||
ultimately selected by the server. For a list of all curves, use:
|
||||
|
||||
$ openssl ecparam -list_curves
|
||||
|
||||
=item B<-cipher cipherlist>
|
||||
|
||||
This allows the TLSv1.2 and below cipher list sent by the client to be modified.
|
||||
This list will be combined with any TLSv1.3 ciphersuites that have been
|
||||
configured. Although the server determines which ciphersuite 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<-ciphersuites val>
|
||||
|
||||
This allows the TLSv1.3 ciphersuites sent by the client to be modified. This
|
||||
list will be combined with any TLSv1.2 and below ciphersuites that have been
|
||||
configured. 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
|
||||
B<ciphers> command for more information. The format for this list is a simple
|
||||
colon (":") separated list of TLSv1.3 ciphersuite names.
|
||||
|
||||
=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", "ftp", "xmpp", "xmpp-server",
|
||||
"irc", "postgres", "mysql", "lmtp", "nntp", "sieve" and "ldap".
|
||||
|
||||
=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.
|
||||
|
||||
This option is an alias of the B<-name> option for "xmpp" and "xmpp-server".
|
||||
|
||||
=item B<-name hostname>
|
||||
|
||||
This option is used to specify hostname information for various protocols
|
||||
used with B<-starttls> option. Currently only "xmpp", "xmpp-server",
|
||||
"smtp" and "lmtp" can utilize this B<-name> option.
|
||||
|
||||
If this option is used with "-starttls xmpp" or "-starttls xmpp-server",
|
||||
if 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.
|
||||
|
||||
If this option is used with "-starttls lmtp" or "-starttls smtp", it specifies
|
||||
the name to use in the "LMTP LHLO" or "SMTP EHLO" message, respectively. If
|
||||
this option is not specified, then "mail.example.com" will be used.
|
||||
|
||||
=item B<-tlsextdebug>
|
||||
|
||||
Print out a hex dump of any TLS extensions received from the server.
|
||||
|
||||
=item B<-no_ticket>
|
||||
|
||||
Disable RFC4507bis session ticket support.
|
||||
|
||||
=item B<-sess_out filename>
|
||||
|
||||
Output SSL session to B<filename>.
|
||||
|
||||
=item B<-sess_in sess.pem>
|
||||
|
||||
Load SSL session from B<filename>. The client will attempt to resume a
|
||||
connection from this session.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<s_client>
|
||||
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<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-serverinfo types>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-status>
|
||||
|
||||
Sends a certificate status request to the server (OCSP stapling). The server
|
||||
response (if any) is printed out.
|
||||
|
||||
=item B<-alpn protocols>, B<-nextprotoneg protocols>
|
||||
|
||||
These flags enable the Enable the Application-Layer Protocol Negotiation
|
||||
or Next Protocol Negotiation (NPN) extension, respectively. ALPN is the
|
||||
IETF standard and replaces NPN.
|
||||
The B<protocols> list is a comma-separated list of protocol names that
|
||||
the client should advertise support for. The list should contain the most
|
||||
desirable protocols first. Protocol names are printable ASCII strings,
|
||||
for example "http/1.1" or "spdy/3".
|
||||
An empty list of protocols is treated specially and will cause the
|
||||
client to advertise support for the TLS extension but disconnect just
|
||||
after receiving ServerHello with a list of server supported protocols.
|
||||
The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used.
|
||||
|
||||
=item B<-ct>, B<-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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-keylogfile file>
|
||||
|
||||
Appends TLS secrets to the specified keylog file such that external programs
|
||||
(like Wireshark) can decrypt TLS connections.
|
||||
|
||||
=item B<-early_data file>
|
||||
|
||||
Reads the contents of the specified file and attempts to send it as early data
|
||||
to the server. This will only work with resumed sessions that support early
|
||||
data and when the server accepts the early data.
|
||||
|
||||
=item B<-enable_pha>
|
||||
|
||||
For TLSv1.3 only, send the Post-Handshake Authentication extension. This will
|
||||
happen whether or not a certificate has been provided via B<-cert>.
|
||||
|
||||
=item B<[target]>
|
||||
|
||||
Rather than providing B<-connect>, the target hostname and optional port may
|
||||
be provided as a single positional argument after all options. If neither this
|
||||
nor B<-connect> are provided, falls back to attempting to connect to localhost
|
||||
on port 4433.
|
||||
|
||||
=back
|
||||
|
||||
=head1 CONNECTED COMMANDS
|
||||
|
||||
If a connection is established with an SSL server then any data received
|
||||
from the server is displayed and any key presses will be sent to the
|
||||
server. If end of file is reached then the connection will be closed down. When
|
||||
used interactively (which means neither B<-quiet> nor B<-ign_eof> have been
|
||||
given), then certain commands are also recognized which perform special
|
||||
operations. These commands are a letter which must appear at the start of a
|
||||
line. They are listed below.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<Q>
|
||||
|
||||
End the current SSL connection and exit.
|
||||
|
||||
=item B<R>
|
||||
|
||||
Renegotiate the SSL session (TLSv1.2 and below only).
|
||||
|
||||
=item B<B>
|
||||
|
||||
Send a heartbeat message to the server (DTLS only)
|
||||
|
||||
=item B<k>
|
||||
|
||||
Send a key update message to the server (TLSv1.3 only)
|
||||
|
||||
=item B<K>
|
||||
|
||||
Send a key update message to the server and request one back (TLSv1.3 only)
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
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
|
||||
|
||||
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<-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.
|
||||
|
||||
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 B<s_client> 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 and send an HTTP request
|
||||
for an appropriate page.
|
||||
|
||||
If a certificate is specified on the command line using the B<-cert>
|
||||
option it will not be used unless the server specifically requests
|
||||
a client certificate. Therefore, merely including a client certificate
|
||||
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 all the certificates sent by the
|
||||
server.
|
||||
|
||||
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
|
||||
applications should B<not> do this as it makes them vulnerable to a MITM
|
||||
attack. This behaviour can be changed by with the B<-verify_return_error>
|
||||
option: any verify errors are then returned aborting the handshake.
|
||||
|
||||
The B<-bind> option may be useful if the server or a firewall requires
|
||||
connections to come from some particular address and or port.
|
||||
|
||||
=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 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<SSL_CONF_cmd(3)>, L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>,
|
||||
L<SSL_CTX_set_max_send_fragment(3)>, L<SSL_CTX_set_split_send_fragment(3)>,
|
||||
L<SSL_CTX_set_max_pipelines(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The B<-no_alt_chains> option was added in OpenSSL 1.1.0.
|
||||
The B<-name> option was added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,855 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-s_server,
|
||||
s_server - SSL/TLS server program
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<s_server>
|
||||
[B<-help>]
|
||||
[B<-port +int>]
|
||||
[B<-accept val>]
|
||||
[B<-unix val>]
|
||||
[B<-4>]
|
||||
[B<-6>]
|
||||
[B<-unlink>]
|
||||
[B<-context val>]
|
||||
[B<-verify int>]
|
||||
[B<-Verify int>]
|
||||
[B<-cert infile>]
|
||||
[B<-nameopt val>]
|
||||
[B<-naccept +int>]
|
||||
[B<-serverinfo val>]
|
||||
[B<-certform PEM|DER>]
|
||||
[B<-key infile>]
|
||||
[B<-keyform format>]
|
||||
[B<-pass val>]
|
||||
[B<-dcert infile>]
|
||||
[B<-dcertform PEM|DER>]
|
||||
[B<-dkey infile>]
|
||||
[B<-dkeyform PEM|DER>]
|
||||
[B<-dpass val>]
|
||||
[B<-nbio_test>]
|
||||
[B<-crlf>]
|
||||
[B<-debug>]
|
||||
[B<-msg>]
|
||||
[B<-msgfile outfile>]
|
||||
[B<-state>]
|
||||
[B<-CAfile infile>]
|
||||
[B<-CApath dir>]
|
||||
[B<-no-CAfile>]
|
||||
[B<-no-CApath>]
|
||||
[B<-nocert>]
|
||||
[B<-quiet>]
|
||||
[B<-no_resume_ephemeral>]
|
||||
[B<-www>]
|
||||
[B<-WWW>]
|
||||
[B<-servername>]
|
||||
[B<-servername_fatal>]
|
||||
[B<-cert2 infile>]
|
||||
[B<-key2 infile>]
|
||||
[B<-tlsextdebug>]
|
||||
[B<-HTTP>]
|
||||
[B<-id_prefix val>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-keymatexport val>]
|
||||
[B<-keymatexportlen +int>]
|
||||
[B<-CRL infile>]
|
||||
[B<-crl_download>]
|
||||
[B<-cert_chain infile>]
|
||||
[B<-dcert_chain infile>]
|
||||
[B<-chainCApath dir>]
|
||||
[B<-verifyCApath dir>]
|
||||
[B<-no_cache>]
|
||||
[B<-ext_cache>]
|
||||
[B<-CRLform PEM|DER>]
|
||||
[B<-verify_return_error>]
|
||||
[B<-verify_quiet>]
|
||||
[B<-build_chain>]
|
||||
[B<-chainCAfile infile>]
|
||||
[B<-verifyCAfile infile>]
|
||||
[B<-ign_eof>]
|
||||
[B<-no_ign_eof>]
|
||||
[B<-status>]
|
||||
[B<-status_verbose>]
|
||||
[B<-status_timeout int>]
|
||||
[B<-status_url val>]
|
||||
[B<-status_file infile>]
|
||||
[B<-trace>]
|
||||
[B<-security_debug>]
|
||||
[B<-security_debug_verbose>]
|
||||
[B<-brief>]
|
||||
[B<-rev>]
|
||||
[B<-async>]
|
||||
[B<-ssl_config val>]
|
||||
[B<-max_send_frag +int>]
|
||||
[B<-split_send_frag +int>]
|
||||
[B<-max_pipelines +int>]
|
||||
[B<-read_buf +int>]
|
||||
[B<-no_ssl3>]
|
||||
[B<-no_tls1>]
|
||||
[B<-no_tls1_1>]
|
||||
[B<-no_tls1_2>]
|
||||
[B<-no_tls1_3>]
|
||||
[B<-bugs>]
|
||||
[B<-no_comp>]
|
||||
[B<-comp>]
|
||||
[B<-no_ticket>]
|
||||
[B<-num_tickets>]
|
||||
[B<-serverpref>]
|
||||
[B<-legacy_renegotiation>]
|
||||
[B<-no_renegotiation>]
|
||||
[B<-legacy_server_connect>]
|
||||
[B<-no_resumption_on_reneg>]
|
||||
[B<-no_legacy_server_connect>]
|
||||
[B<-allow_no_dhe_kex>]
|
||||
[B<-prioritize_chacha>]
|
||||
[B<-strict>]
|
||||
[B<-sigalgs val>]
|
||||
[B<-client_sigalgs val>]
|
||||
[B<-groups val>]
|
||||
[B<-curves val>]
|
||||
[B<-named_curve val>]
|
||||
[B<-cipher val>]
|
||||
[B<-ciphersuites val>]
|
||||
[B<-dhparam infile>]
|
||||
[B<-record_padding val>]
|
||||
[B<-debug_broken_protocol>]
|
||||
[B<-policy val>]
|
||||
[B<-purpose val>]
|
||||
[B<-verify_name val>]
|
||||
[B<-verify_depth int>]
|
||||
[B<-auth_level int>]
|
||||
[B<-attime intmax>]
|
||||
[B<-verify_hostname val>]
|
||||
[B<-verify_email val>]
|
||||
[B<-verify_ip>]
|
||||
[B<-ignore_critical>]
|
||||
[B<-issuer_checks>]
|
||||
[B<-crl_check>]
|
||||
[B<-crl_check_all>]
|
||||
[B<-policy_check>]
|
||||
[B<-explicit_policy>]
|
||||
[B<-inhibit_any>]
|
||||
[B<-inhibit_map>]
|
||||
[B<-x509_strict>]
|
||||
[B<-extended_crl>]
|
||||
[B<-use_deltas>]
|
||||
[B<-policy_print>]
|
||||
[B<-check_ss_sig>]
|
||||
[B<-trusted_first>]
|
||||
[B<-suiteB_128_only>]
|
||||
[B<-suiteB_128>]
|
||||
[B<-suiteB_192>]
|
||||
[B<-partial_chain>]
|
||||
[B<-no_alt_chains>]
|
||||
[B<-no_check_time>]
|
||||
[B<-allow_proxy_certs>]
|
||||
[B<-xkey>]
|
||||
[B<-xcert>]
|
||||
[B<-xchain>]
|
||||
[B<-xchain_build>]
|
||||
[B<-xcertform PEM|DER>]
|
||||
[B<-xkeyform PEM|DER>]
|
||||
[B<-nbio>]
|
||||
[B<-psk_identity val>]
|
||||
[B<-psk_hint val>]
|
||||
[B<-psk val>]
|
||||
[B<-psk_session file>]
|
||||
[B<-srpvfile infile>]
|
||||
[B<-srpuserseed val>]
|
||||
[B<-ssl3>]
|
||||
[B<-tls1>]
|
||||
[B<-tls1_1>]
|
||||
[B<-tls1_2>]
|
||||
[B<-tls1_3>]
|
||||
[B<-dtls>]
|
||||
[B<-timeout>]
|
||||
[B<-mtu +int>]
|
||||
[B<-listen>]
|
||||
[B<-dtls1>]
|
||||
[B<-dtls1_2>]
|
||||
[B<-sctp>]
|
||||
[B<-sctp_label_bug>]
|
||||
[B<-no_dhe>]
|
||||
[B<-nextprotoneg val>]
|
||||
[B<-use_srtp val>]
|
||||
[B<-alpn val>]
|
||||
[B<-engine val>]
|
||||
[B<-keylogfile outfile>]
|
||||
[B<-max_early_data int>]
|
||||
[B<-early_data>]
|
||||
[B<-anti_replay>]
|
||||
[B<-no_anti_replay>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<s_server> command implements a generic SSL/TLS server which listens
|
||||
for connections on a given port using 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 "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
|
||||
manual page.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Print out a usage message.
|
||||
|
||||
=item B<-port +int>
|
||||
|
||||
The TCP port to listen on for connections. If not specified 4433 is used.
|
||||
|
||||
=item B<-accept val>
|
||||
|
||||
The optional TCP host and port to listen on for connections. If not specified, *:4433 is used.
|
||||
|
||||
=item B<-unix val>
|
||||
|
||||
Unix domain socket to accept on.
|
||||
|
||||
=item B<-4>
|
||||
|
||||
Use IPv4 only.
|
||||
|
||||
=item B<-6>
|
||||
|
||||
Use IPv6 only.
|
||||
|
||||
=item B<-unlink>
|
||||
|
||||
For -unix, unlink any existing socket first.
|
||||
|
||||
=item B<-context val>
|
||||
|
||||
Sets the SSL context id. It can be given any string value. If this option
|
||||
is not present a default value will be used.
|
||||
|
||||
=item B<-verify int>, B<-Verify int>
|
||||
|
||||
The verify depth to use. This specifies the maximum length of the
|
||||
client certificate chain and makes the server request a certificate from
|
||||
the client. With the B<-verify> option a certificate is requested but the
|
||||
client does not have to send one, with the B<-Verify> option the client
|
||||
must supply a certificate or an error occurs.
|
||||
|
||||
If the cipher suite cannot request a client certificate (for example an
|
||||
anonymous cipher suite or PSK) this option has no effect.
|
||||
|
||||
=item B<-cert infile>
|
||||
|
||||
The certificate to use, most servers cipher suites require the use of a
|
||||
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.
|
||||
|
||||
=item B<-cert_chain>
|
||||
|
||||
A file containing trusted certificates to use when attempting to build the
|
||||
client/server certificate chain related to the certificate specified via the
|
||||
B<-cert> option.
|
||||
|
||||
=item B<-build_chain>
|
||||
|
||||
Specify whether the application should build the certificate chain to be
|
||||
provided to the client.
|
||||
|
||||
=item B<-nameopt val>
|
||||
|
||||
Option which determines how the subject or issuer names are displayed. The
|
||||
B<val> 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)> manual page for details.
|
||||
|
||||
=item B<-naccept +int>
|
||||
|
||||
The server will exit after receiving the specified number of connections,
|
||||
default unlimited.
|
||||
|
||||
=item B<-serverinfo val>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-certform PEM|DER>
|
||||
|
||||
The certificate format to use: DER or PEM. PEM is the default.
|
||||
|
||||
=item B<-key infile>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-pass val>
|
||||
|
||||
The private key password source. For more information about the format of B<val>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-dcert infile>, B<-dkey infile>
|
||||
|
||||
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
|
||||
a certain type. Some cipher suites need a certificate carrying an RSA key
|
||||
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.
|
||||
|
||||
=item B<-dcert_chain>
|
||||
|
||||
A file containing trusted certificates to use when attempting to build the
|
||||
server certificate chain when a certificate specified via the B<-dcert> option
|
||||
is in use.
|
||||
|
||||
=item B<-dcertform PEM|DER>, B<-dkeyform PEM|DER>, B<-dpass val>
|
||||
|
||||
Additional certificate and private key format and passphrase respectively.
|
||||
|
||||
=item B<-xkey infile>, B<-xcert infile>, B<-xchain>
|
||||
|
||||
Specify an extra certificate, private key and certificate chain. These behave
|
||||
in the same manner as the B<-cert>, B<-key> and B<-cert_chain> options. When
|
||||
specified, the callback returning the first valid chain will be in use by
|
||||
the server.
|
||||
|
||||
=item B<-xchain_build>
|
||||
|
||||
Specify whether the application should build the certificate chain to be
|
||||
provided to the client for the extra certificates provided via B<-xkey infile>,
|
||||
B<-xcert infile>, B<-xchain> options.
|
||||
|
||||
=item B<-xcertform PEM|DER>, B<-xkeyform PEM|DER>
|
||||
|
||||
Extra certificate and private key format respectively.
|
||||
|
||||
=item B<-nbio_test>
|
||||
|
||||
Tests non blocking I/O.
|
||||
|
||||
=item B<-crlf>
|
||||
|
||||
This option translated a line feed from the terminal into CR+LF.
|
||||
|
||||
=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<-msgfile outfile>
|
||||
|
||||
File to send output of B<-msg> or B<-trace> to, default standard output.
|
||||
|
||||
=item B<-state>
|
||||
|
||||
Prints the SSL session states.
|
||||
|
||||
=item B<-CAfile infile>
|
||||
|
||||
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<-CApath dir>
|
||||
|
||||
The directory to use for client certificate verification. This directory
|
||||
must be in "hash format", see L<verify(1)> for more information. These are
|
||||
also used when building the server certificate chain.
|
||||
|
||||
=item B<-chainCApath dir>
|
||||
|
||||
The directory to use for building the chain provided to the client. This
|
||||
directory must be in "hash format", see L<verify(1)> for more information.
|
||||
|
||||
=item B<-chainCAfile file>
|
||||
|
||||
A file containing trusted certificates to use when attempting to build the
|
||||
server 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<-nocert>
|
||||
|
||||
If this option is set then no certificate is used. This restricts the
|
||||
cipher suites available to the anonymous ones (currently just anonymous
|
||||
DH).
|
||||
|
||||
=item B<-quiet>
|
||||
|
||||
Inhibit printing of session and certificate information.
|
||||
|
||||
=item B<-www>
|
||||
|
||||
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. Cannot be used in conjunction with B<-early_data>.
|
||||
|
||||
=item B<-WWW>
|
||||
|
||||
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. Cannot be used in conjunction
|
||||
with B<-early_data>.
|
||||
|
||||
=item B<-tlsextdebug>
|
||||
|
||||
Print a hex dump of any TLS extensions received from the server.
|
||||
|
||||
=item B<-HTTP>
|
||||
|
||||
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). Cannot be
|
||||
used in conjunction with B<-early_data>.
|
||||
|
||||
=item B<-id_prefix val>
|
||||
|
||||
Generate SSL/TLS session IDs prefixed by B<val>. This is mostly useful
|
||||
for testing any SSL/TLS code (e.g. proxies) that wish to deal with multiple
|
||||
servers, when each of which might be generating a unique range of session
|
||||
IDs (e.g. with a certain prefix).
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-verify_return_error>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-status>
|
||||
|
||||
Enables certificate status request support (aka OCSP stapling).
|
||||
|
||||
=item B<-status_verbose>
|
||||
|
||||
Enables certificate status request support (aka OCSP stapling) and gives
|
||||
a verbose printout of the OCSP response.
|
||||
|
||||
=item B<-status_timeout int>
|
||||
|
||||
Sets the timeout for OCSP response to B<int> seconds.
|
||||
|
||||
=item B<-status_url val>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-status_file infile>
|
||||
|
||||
Overrides any OCSP responder URLs from the certificate and always provides the
|
||||
OCSP Response stored in the file. The file must be in DER format.
|
||||
|
||||
=item B<-trace>
|
||||
|
||||
Show verbose trace output of protocol messages. OpenSSL needs to be compiled
|
||||
with B<enable-ssl-trace> for this option to work.
|
||||
|
||||
=item B<-brief>
|
||||
|
||||
Provide a brief summary of connection parameters instead of the normal verbose
|
||||
output.
|
||||
|
||||
=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>. Cannot be used in
|
||||
conjunction with B<-early_data>.
|
||||
|
||||
=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).
|
||||
|
||||
=item B<-max_send_frag +int>
|
||||
|
||||
The maximum size of data fragment to send.
|
||||
See L<SSL_CTX_set_max_send_fragment(3)> for further information.
|
||||
|
||||
=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 cipher suite 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.
|
||||
|
||||
=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 cipher suite has been negotiated. The default value is 1.
|
||||
See L<SSL_CTX_set_max_pipelines(3)> for further information.
|
||||
|
||||
=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).
|
||||
|
||||
=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 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.
|
||||
Note that not all protocols and flags may be available, depending on how
|
||||
OpenSSL was built.
|
||||
|
||||
=item B<-bugs>
|
||||
|
||||
There are several known bugs in SSL and TLS implementations. Adding this
|
||||
option enables various workarounds.
|
||||
|
||||
=item B<-no_comp>
|
||||
|
||||
Disable negotiation of TLS compression.
|
||||
TLS compression is not recommended and is off by default as of
|
||||
OpenSSL 1.1.0.
|
||||
|
||||
=item B<-comp>
|
||||
|
||||
Enable negotiation of TLS compression.
|
||||
This option was introduced in OpenSSL 1.1.0.
|
||||
TLS compression is not recommended and is off by default as of
|
||||
OpenSSL 1.1.0.
|
||||
|
||||
=item B<-no_ticket>
|
||||
|
||||
Disable RFC4507bis session ticket support. This option has no effect if TLSv1.3
|
||||
is negotiated. See B<-num_tickets>.
|
||||
|
||||
=item B<-num_tickets>
|
||||
|
||||
Control the number of tickets that will be sent to the client after a full
|
||||
handshake in TLSv1.3. The default number of tickets is 2. This option does not
|
||||
affect the number of tickets sent after a resumption handshake.
|
||||
|
||||
=item B<-serverpref>
|
||||
|
||||
Use the server's cipher preferences, rather than the client's preferences.
|
||||
|
||||
=item B<-prioritize_chacha>
|
||||
|
||||
Prioritize ChaCha ciphers when preferred by clients. Requires B<-serverpref>.
|
||||
|
||||
=item B<-no_resumption_on_reneg>
|
||||
|
||||
Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option.
|
||||
|
||||
=item B<-client_sigalgs val>
|
||||
|
||||
Signature algorithms to support for client certificate authentication
|
||||
(colon-separated list).
|
||||
|
||||
=item B<-named_curve val>
|
||||
|
||||
Specifies the elliptic curve to use. NOTE: this is single curve, not a list.
|
||||
For a list of all possible curves, use:
|
||||
|
||||
$ openssl ecparam -list_curves
|
||||
|
||||
=item B<-cipher val>
|
||||
|
||||
This allows the list of TLSv1.2 and below ciphersuites used by the server to be
|
||||
modified. This list is combined with any TLSv1.3 ciphersuites that have been
|
||||
configured. 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 is irrelevant. See
|
||||
the B<ciphers> command for more information.
|
||||
|
||||
=item B<-ciphersuites val>
|
||||
|
||||
This allows the list of TLSv1.3 ciphersuites used by the server to be modified.
|
||||
This list is combined with any TLSv1.2 and below ciphersuites that have been
|
||||
configured. 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 is irrelevant. See
|
||||
the B<ciphers> command for more information. The format for this list is a
|
||||
simple colon (":") separated list of TLSv1.3 ciphersuite names.
|
||||
|
||||
=item B<-dhparam infile>
|
||||
|
||||
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 B<s_server>
|
||||
program will be used.
|
||||
|
||||
=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 peer certificate verification options.
|
||||
See the L<verify(1)> manual page for details.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-nbio>
|
||||
|
||||
Turns on non blocking I/O.
|
||||
|
||||
=item B<-psk_identity val>
|
||||
|
||||
Expect the client to send PSK identity B<val> when using a PSK
|
||||
cipher suite, and warn if they do not. By default, the expected PSK
|
||||
identity is the string "Client_identity".
|
||||
|
||||
=item B<-psk_hint val>
|
||||
|
||||
Use the PSK identity hint B<val> when using a PSK cipher suite.
|
||||
|
||||
=item B<-psk val>
|
||||
|
||||
Use the PSK key B<val> 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<-psk_session file>
|
||||
|
||||
Use the pem encoded SSL_SESSION data stored in B<file> as the basis of a PSK.
|
||||
Note that this will only work if TLSv1.3 is negotiated.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-sctp>
|
||||
|
||||
Use SCTP for the transport protocol instead of UDP in DTLS. Must be used in
|
||||
conjunction with B<-dtls>, B<-dtls1> or B<-dtls1_2>. This option is only
|
||||
available where OpenSSL has support for SCTP enabled.
|
||||
|
||||
=item B<-sctp_label_bug>
|
||||
|
||||
Use the incorrect behaviour of older OpenSSL implementations when computing
|
||||
endpoint-pair shared secrets for DTLS/SCTP. This allows communication with
|
||||
older broken implementations but breaks interoperability with correct
|
||||
implementations. Must be used in conjunction with B<-sctp>. This option is only
|
||||
available where OpenSSL has support for SCTP enabled.
|
||||
|
||||
=item B<-no_dhe>
|
||||
|
||||
If this option is set then no DH parameters will be loaded effectively
|
||||
disabling the ephemeral DH cipher suites.
|
||||
|
||||
=item B<-alpn val>, B<-nextprotoneg val>
|
||||
|
||||
These flags enable the Enable the Application-Layer Protocol Negotiation
|
||||
or Next Protocol Negotiation (NPN) extension, respectively. ALPN is the
|
||||
IETF standard and replaces NPN.
|
||||
The B<val> list is a comma-separated list of supported protocol
|
||||
names. The list should contain the most desirable protocols first.
|
||||
Protocol names are printable ASCII strings, for example "http/1.1" or
|
||||
"spdy/3".
|
||||
The flag B<-nextprotoneg> cannot be specified if B<-tls1_3> is used.
|
||||
|
||||
=item B<-engine val>
|
||||
|
||||
Specifying an engine (by its unique id string in B<val>) 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.
|
||||
|
||||
=item B<-keylogfile outfile>
|
||||
|
||||
Appends TLS secrets to the specified keylog file such that external programs
|
||||
(like Wireshark) can decrypt TLS connections.
|
||||
|
||||
=item B<-max_early_data int>
|
||||
|
||||
Change the default maximum early data bytes that are specified for new sessions
|
||||
and any incoming early data (when used in conjunction with the B<-early_data>
|
||||
flag). The default value is approximately 16k. The argument must be an integer
|
||||
greater than or equal to 0.
|
||||
|
||||
=item B<-early_data>
|
||||
|
||||
Accept early data where possible. Cannot be used in conjunction with B<-www>,
|
||||
B<-WWW>, B<-HTTP> or B<-rev>.
|
||||
|
||||
=item B<-anti_replay>, B<-no_anti_replay>
|
||||
|
||||
Switches replay protection on or off, respectively. Replay protection is on by
|
||||
default unless overridden by a configuration file. When it is on, OpenSSL will
|
||||
automatically detect if a session ticket has been used more than once, TLSv1.3
|
||||
has been negotiated, and early data is enabled on the server. A full handshake
|
||||
is forced if a session ticket is used a second or subsequent time. Any early
|
||||
data that was sent will be rejected.
|
||||
|
||||
=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.
|
||||
|
||||
Certain commands are also recognized which perform special operations. These
|
||||
commands are a letter which must appear at the start of a line. They are listed
|
||||
below.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<q>
|
||||
|
||||
End the current SSL connection but still accept new connections.
|
||||
|
||||
=item B<Q>
|
||||
|
||||
End the current SSL connection and exit.
|
||||
|
||||
=item B<r>
|
||||
|
||||
Renegotiate the SSL session (TLSv1.2 and below only).
|
||||
|
||||
=item B<R>
|
||||
|
||||
Renegotiate the SSL session and request a client certificate (TLSv1.2 and below
|
||||
only).
|
||||
|
||||
=item B<P>
|
||||
|
||||
Send some plain text down the underlying TCP connection: this should
|
||||
cause the client to disconnect due to a protocol violation.
|
||||
|
||||
=item B<S>
|
||||
|
||||
Print out some session cache status information.
|
||||
|
||||
=item B<B>
|
||||
|
||||
Send a heartbeat message to the client (DTLS only)
|
||||
|
||||
=item B<k>
|
||||
|
||||
Send a key update message to the client (TLSv1.3 only)
|
||||
|
||||
=item B<K>
|
||||
|
||||
Send a key update message to the client and request one back (TLSv1.3 only)
|
||||
|
||||
=item B<c>
|
||||
|
||||
Send a certificate request to the client (TLSv1.3 only)
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
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
|
||||
|
||||
can be used for example.
|
||||
|
||||
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.
|
||||
|
||||
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 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.
|
||||
|
||||
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<SSL_CONF_cmd(3)>, L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)>
|
||||
L<SSL_CTX_set_max_send_fragment(3)>,
|
||||
L<SSL_CTX_set_split_send_fragment(3)>,
|
||||
L<SSL_CTX_set_max_pipelines(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The -no_alt_chains option was added in OpenSSL 1.1.0.
|
||||
|
||||
The
|
||||
-allow-no-dhe-kex and -prioritize_chacha options were added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,212 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-s_time,
|
||||
s_time - SSL/TLS performance timing program
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> 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<-nameopt option>]
|
||||
[B<-time seconds>]
|
||||
[B<-ssl3>]
|
||||
[B<-bugs>]
|
||||
[B<-cipher cipherlist>]
|
||||
[B<-ciphersuites val>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<s_time> command implements a generic SSL/TLS client which connects to a
|
||||
remote host using SSL/TLS. It can request a page from the server and includes
|
||||
the time to transfer the payload data in its timing measurements. It measures
|
||||
the number of connections within a given timeframe, the amount of data
|
||||
transferred (if any), and calculates the average time spent for one connection.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-www page>
|
||||
|
||||
This specifies the page to GET from the server. A value of '/' gets the
|
||||
index.htm[l] page. If this parameter is not specified, then B<s_time> will only
|
||||
perform the handshake to establish SSL connections but not transfer any
|
||||
payload data.
|
||||
|
||||
=item B<-cert certname>
|
||||
|
||||
The certificate to use, if one is requested by the server. The default is
|
||||
not to use a certificate. The file is in PEM format.
|
||||
|
||||
=item B<-key keyfile>
|
||||
|
||||
The private key to use. If not specified then the certificate file will
|
||||
be used. The file is in PEM format.
|
||||
|
||||
=item B<-verify depth>
|
||||
|
||||
The verify depth to use. This specifies the maximum length of the
|
||||
server certificate chain and turns on server certificate verification.
|
||||
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<-nameopt option>
|
||||
|
||||
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)> manual page for details.
|
||||
|
||||
=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<-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.
|
||||
If neither B<-new> nor B<-reuse> are specified, they are both on by default
|
||||
and executed in sequence.
|
||||
|
||||
=item B<-reuse>
|
||||
|
||||
Performs the timing test using the same session ID; this can be used as a test
|
||||
that session caching is working. If neither B<-new> nor B<-reuse> are
|
||||
specified, they are both on by default and executed in sequence.
|
||||
|
||||
=item B<-ssl3>
|
||||
|
||||
This option disables the use of SSL version 3. By default
|
||||
the initial handshake uses a method which should be compatible with all
|
||||
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)> 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.
|
||||
|
||||
Note that this option may not be available, depending on how
|
||||
OpenSSL was built.
|
||||
|
||||
=item B<-bugs>
|
||||
|
||||
There are several known bugs in SSL and TLS implementations. Adding this
|
||||
option enables various workarounds.
|
||||
|
||||
=item B<-cipher cipherlist>
|
||||
|
||||
This allows the TLSv1.2 and below cipher list sent by the client to be modified.
|
||||
This list will be combined with any TLSv1.3 ciphersuites that have been
|
||||
configured. Although the server determines which cipher suite is used it should
|
||||
take the first supported cipher in the list sent by the client. See
|
||||
L<ciphers(1)> for more information.
|
||||
|
||||
=item B<-ciphersuites val>
|
||||
|
||||
This allows the TLSv1.3 ciphersuites sent by the client to be modified. This
|
||||
list will be combined with any TLSv1.2 and below ciphersuites that have been
|
||||
configured. Although the server determines which cipher suite is used it should
|
||||
take the first supported cipher in the list sent by the client. See
|
||||
L<ciphers(1)> for more information. The format for this list is a simple
|
||||
colon (":") separated list of TLSv1.3 ciphersuite names.
|
||||
|
||||
=item B<-time length>
|
||||
|
||||
Specifies how long (in seconds) B<s_time> should establish connections and
|
||||
optionally transfer payload data from a server. Server and client performance
|
||||
and the link speed determine how many connections B<s_time> can establish.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
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]
|
||||
|
||||
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)> 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> 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.
|
||||
|
||||
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)> 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)> and
|
||||
send an HTTP request for an appropriate page.
|
||||
|
||||
If a certificate is specified on the command line using the B<-cert>
|
||||
option it will not be used unless the server specifically requests
|
||||
a client certificate. Therefore, merely including a client certificate
|
||||
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)> 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
|
||||
fails.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<s_client(1)>, L<s_server(1)>, L<ciphers(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2004-2020 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
|
||||
@@ -0,0 +1,166 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-sess_id,
|
||||
sess_id - SSL/TLS session handling utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<sess_id>
|
||||
[B<-help>]
|
||||
[B<-inform PEM|DER>]
|
||||
[B<-outform PEM|DER|NSS>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-text>]
|
||||
[B<-noout>]
|
||||
[B<-context ID>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<sess_id> process the encoded version of the SSL session structure
|
||||
and optionally prints out SSL session details (for example the SSL session
|
||||
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
|
||||
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|NSS>
|
||||
|
||||
This specifies the output format. The B<PEM> and B<DER> options have the same meaning
|
||||
and default 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>
|
||||
|
||||
This specifies the input filename to read session information from or standard
|
||||
input by default.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
This specifies the output filename to write session information to or standard
|
||||
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.
|
||||
|
||||
=item B<-cert>
|
||||
|
||||
If a certificate is present in the session it will be output using this option,
|
||||
if the B<-text> option is also present then it will be printed out in text form.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
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 won't normally
|
||||
be used.
|
||||
|
||||
=back
|
||||
|
||||
=head1 OUTPUT
|
||||
|
||||
Typical output:
|
||||
|
||||
SSL-Session:
|
||||
Protocol : TLSv1
|
||||
Cipher : 0016
|
||||
Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED
|
||||
Session-ID-ctx: 01000000
|
||||
Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD
|
||||
Key-Arg : None
|
||||
Start Time: 948459261
|
||||
Timeout : 300 (sec)
|
||||
Verify return code 0 (ok)
|
||||
|
||||
These are described below in more detail.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<Protocol>
|
||||
|
||||
This is the protocol in use TLSv1.3, TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
|
||||
|
||||
=item B<Cipher>
|
||||
|
||||
The cipher used this is the actual raw SSL or TLS cipher code, see the SSL
|
||||
or TLS specifications for more information.
|
||||
|
||||
=item B<Session-ID>
|
||||
|
||||
The SSL session ID in hex format.
|
||||
|
||||
=item B<Session-ID-ctx>
|
||||
|
||||
The session ID context in hex format.
|
||||
|
||||
=item B<Master-Key>
|
||||
|
||||
This is the SSL session master key.
|
||||
|
||||
=item B<Start Time>
|
||||
|
||||
This is the session start time represented as an integer in standard
|
||||
Unix format.
|
||||
|
||||
=item B<Timeout>
|
||||
|
||||
The timeout in seconds.
|
||||
|
||||
=item B<Verify return code>
|
||||
|
||||
This is the return code when an SSL client certificate is verified.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The PEM encoded session format uses the header and footer lines:
|
||||
|
||||
-----BEGIN SSL SESSION PARAMETERS-----
|
||||
-----END SSL SESSION PARAMETERS-----
|
||||
|
||||
Since the SSL session output contains the master key it is
|
||||
possible to read the contents of an encrypted session using this
|
||||
information. Therefore, appropriate security precautions should be taken if
|
||||
the information is being output by a "real" application. This is however
|
||||
strongly discouraged and should only be used for debugging purposes.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The cipher and start time should be printed out in human readable form.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ciphers(1)>, L<s_server(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,524 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-smime,
|
||||
smime - S/MIME utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<smime>
|
||||
[B<-help>]
|
||||
[B<-encrypt>]
|
||||
[B<-decrypt>]
|
||||
[B<-sign>]
|
||||
[B<-resign>]
|
||||
[B<-verify>]
|
||||
[B<-pk7out>]
|
||||
[B<-binary>]
|
||||
[B<-crlfeol>]
|
||||
[B<-I<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>]
|
||||
[B<-inform SMIME|PEM|DER>]
|
||||
[B<-passin arg>]
|
||||
[B<-inkey file_or_id>]
|
||||
[B<-out file>]
|
||||
[B<-outform SMIME|PEM|DER>]
|
||||
[B<-content file>]
|
||||
[B<-to addr>]
|
||||
[B<-from ad>]
|
||||
[B<-subject s>]
|
||||
[B<-text>]
|
||||
[B<-indef>]
|
||||
[B<-noindef>]
|
||||
[B<-stream>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-md digest>]
|
||||
[cert.pem]...
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
|
||||
verify S/MIME messages.
|
||||
|
||||
=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
|
||||
to be encrypted. The output file is the encrypted mail in MIME format.
|
||||
|
||||
Note that no revocation check is done for the recipient cert, so if that
|
||||
key has been compromised, others may be able to decrypt the text.
|
||||
|
||||
=item B<-decrypt>
|
||||
|
||||
Decrypt mail using the supplied certificate and private key. Expects an
|
||||
encrypted mail message in MIME format for the input file. The decrypted mail
|
||||
is written to the output file.
|
||||
|
||||
=item B<-sign>
|
||||
|
||||
Sign mail using the supplied certificate and private key. Input file is
|
||||
the message to be signed. The signed message in MIME format is written
|
||||
to the output file.
|
||||
|
||||
=item B<-verify>
|
||||
|
||||
Verify signed mail. Expects a signed mail message on input and outputs
|
||||
the signed data. Both clear text and opaque signing is supported.
|
||||
|
||||
=item B<-pk7out>
|
||||
|
||||
Takes an input message and writes out a PEM encoded PKCS#7 structure.
|
||||
|
||||
=item B<-resign>
|
||||
|
||||
Resign a message: take an existing message and one or more new signers.
|
||||
|
||||
=item B<-in filename>
|
||||
|
||||
The input message to be encrypted or signed or the MIME message to
|
||||
be decrypted or verified.
|
||||
|
||||
=item B<-inform SMIME|PEM|DER>
|
||||
|
||||
This specifies the input format for the PKCS#7 structure. The default
|
||||
is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
|
||||
format change this to expect PEM and DER format PKCS#7 structures
|
||||
instead. This currently only affects the input format of the PKCS#7
|
||||
structure, if no PKCS#7 structure is being input (for example with
|
||||
B<-encrypt> or B<-sign>) this option has no effect.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
The message text that has been decrypted or verified or the output MIME
|
||||
format message that has been signed or verified.
|
||||
|
||||
=item B<-outform SMIME|PEM|DER>
|
||||
|
||||
This specifies the output format for the PKCS#7 structure. The default
|
||||
is B<SMIME> which write an S/MIME format message. B<PEM> and B<DER>
|
||||
format change this to write PEM and DER format PKCS#7 structures
|
||||
instead. This currently only affects the output format of the PKCS#7
|
||||
structure, if no PKCS#7 structure is being output (for example with
|
||||
B<-verify> or B<-decrypt>) this option has no effect.
|
||||
|
||||
=item B<-stream -indef -noindef>
|
||||
|
||||
The B<-stream> and B<-indef> options are equivalent and enable streaming I/O
|
||||
for encoding operations. This permits single pass processing of data without
|
||||
the need to hold the entire contents in memory, potentially supporting very
|
||||
large files. Streaming is automatically set for S/MIME signing with detached
|
||||
data if the output format is B<SMIME> it is currently off by default for all
|
||||
other operations.
|
||||
|
||||
=item B<-noindef>
|
||||
|
||||
Disable streaming I/O where it would produce and indefinite length constructed
|
||||
encoding. This option currently has no effect. In future streaming will be
|
||||
enabled by default on all relevant operations and this option will disable it.
|
||||
|
||||
=item B<-content filename>
|
||||
|
||||
This specifies a file containing the detached content, this is only
|
||||
useful with the B<-verify> command. This is only usable if the PKCS#7
|
||||
structure is using the detached signature form where the content is
|
||||
not included. This option will override any content if the input format
|
||||
is S/MIME and it uses the multipart/signed MIME content type.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
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
|
||||
type text/plain then an error occurs.
|
||||
|
||||
=item B<-CAfile file>
|
||||
|
||||
A file containing trusted CA certificates, only used with B<-verify>.
|
||||
|
||||
=item B<-CApath dir>
|
||||
|
||||
A directory containing trusted CA certificates, only used with
|
||||
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
|
||||
default digest algorithm for the signing key will be used (usually SHA1).
|
||||
|
||||
=item B<-I<cipher>>
|
||||
|
||||
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.
|
||||
|
||||
If not specified triple DES is used. Only used with B<-encrypt>.
|
||||
|
||||
=item B<-nointern>
|
||||
|
||||
When verifying a message normally certificates (if any) included in
|
||||
the message are searched for the signing certificate. With this option
|
||||
only the certificates specified in the B<-certfile> option are used.
|
||||
The supplied certificates can still be used as untrusted CAs however.
|
||||
|
||||
=item B<-noverify>
|
||||
|
||||
Do not verify the signers certificate of a signed message.
|
||||
|
||||
=item B<-nochain>
|
||||
|
||||
Do not do chain verification of signers certificates: that is don't
|
||||
use the certificates in the signed message as untrusted CAs.
|
||||
|
||||
=item B<-nosigs>
|
||||
|
||||
Don't try to verify the signatures on the message.
|
||||
|
||||
=item B<-nocerts>
|
||||
|
||||
When signing a message the signer's certificate is normally included
|
||||
with this option it is excluded. This will reduce the size of the
|
||||
signed message but the verifier must have a copy of the signers certificate
|
||||
available locally (passed using the B<-certfile> option for example).
|
||||
|
||||
=item B<-noattr>
|
||||
|
||||
Normally when a message is signed a set of attributes are included which
|
||||
include the signing time and supported symmetric algorithms. With this
|
||||
option they are not included.
|
||||
|
||||
=item B<-binary>
|
||||
|
||||
Normally the input message is converted to "canonical" format which is
|
||||
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
|
||||
to translation by mail relays but it cannot be read by mail agents that
|
||||
do not support S/MIME. Without this option cleartext signing with
|
||||
the MIME type multipart/signed is used.
|
||||
|
||||
=item B<-certfile file>
|
||||
|
||||
Allows additional certificates to be specified. When signing these will
|
||||
be included with the message. When verifying these will be searched for
|
||||
the signers certificates. The certificates should be in PEM format.
|
||||
|
||||
=item B<-signer file>
|
||||
|
||||
A signing certificate when signing or resigning a message, this option can be
|
||||
used multiple times if more than one signer is required. If a message is being
|
||||
verified then the signers certificates will be written to this file if the
|
||||
verification was successful.
|
||||
|
||||
=item B<-recip file>
|
||||
|
||||
The recipients certificate when decrypting a message. This certificate
|
||||
must match one of the recipients of the message or an error occurs.
|
||||
|
||||
=item B<-inkey file_or_id>
|
||||
|
||||
The private key to use when signing or decrypting. This must match the
|
||||
corresponding certificate. If this option is not specified then the
|
||||
private key must be included in the certificate file specified with
|
||||
the B<-recip> or B<-signer> file. When signing this option can be used
|
||||
multiple times to specify successive keys.
|
||||
If no engine is used, the argument is taken as a file; if an engine is
|
||||
specified, the argument is given to the engine as a key identifier.
|
||||
|
||||
=item B<-passin arg>
|
||||
|
||||
The private key password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<cert.pem...>
|
||||
|
||||
One or more certificates of message recipients: used when encrypting
|
||||
a message.
|
||||
|
||||
=item B<-to, -from, -subject>
|
||||
|
||||
The relevant mail headers. These are included outside the signed
|
||||
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<-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<verify(1)> manual page for details.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The MIME message must be sent without any blank lines between the
|
||||
headers and the output. Some mail programs will automatically add
|
||||
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 won't display it
|
||||
properly (if at all). You can use the B<-text> option to automatically
|
||||
add plain text headers.
|
||||
|
||||
A "signed and encrypted" message is one where a signed message is
|
||||
then encrypted. This can be produced by encrypting an already signed
|
||||
message: see the examples section.
|
||||
|
||||
This version of the program only allows one signer per message but it
|
||||
will verify multiple signers on received messages. Some S/MIME clients
|
||||
choke if a message contains multiple signers. It is possible to sign
|
||||
messages "in parallel" by signing an already signed message.
|
||||
|
||||
The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
|
||||
clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
|
||||
encrypted data is used for other purposes.
|
||||
|
||||
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 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.
|
||||
|
||||
Streaming is always used for the B<-sign> operation with detached data but
|
||||
since the content is no longer part of the PKCS#7 structure the encoding
|
||||
remains DER.
|
||||
|
||||
=head1 EXIT CODES
|
||||
|
||||
=over 4
|
||||
|
||||
=item Z<>0
|
||||
|
||||
The operation was completely successfully.
|
||||
|
||||
=item Z<>1
|
||||
|
||||
An error occurred parsing the command options.
|
||||
|
||||
=item Z<>2
|
||||
|
||||
One of the input files could not be read.
|
||||
|
||||
=item Z<>3
|
||||
|
||||
An error occurred creating the PKCS#7 file or when reading the MIME
|
||||
message.
|
||||
|
||||
=item Z<>4
|
||||
|
||||
An error occurred decrypting or verifying the message.
|
||||
|
||||
=item Z<>5
|
||||
|
||||
The message was verified correctly but an error occurred writing out
|
||||
the signers certificates.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Create a cleartext signed message:
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
Create a signed message with two signers:
|
||||
|
||||
openssl 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
|
||||
|
||||
Verify a message and extract the signer's certificate if successful:
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
The output from Netscape form signing is a PKCS#7 structure with the
|
||||
detached signature format. You can use this program to verify the
|
||||
signature by line wrapping the base64 encoded structure and surrounding
|
||||
it with:
|
||||
|
||||
-----BEGIN PKCS7-----
|
||||
-----END PKCS7-----
|
||||
|
||||
and using the command:
|
||||
|
||||
openssl 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
|
||||
|
||||
Create an encrypted message using 128 bit Camellia:
|
||||
|
||||
openssl 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
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The MIME parser isn't very clever: it seems to handle most messages that I've
|
||||
thrown at it but it may choke on others.
|
||||
|
||||
The code currently will only write out the signer's certificate to a file: if
|
||||
the signer has a separate encryption certificate this must be manually
|
||||
extracted. There should be some heuristic that determines the correct
|
||||
encryption certificate.
|
||||
|
||||
Ideally a database should be maintained of a certificates for each email
|
||||
address.
|
||||
|
||||
The code doesn't currently take note of the permitted symmetric encryption
|
||||
algorithms as supplied in the SMIMECapabilities signed attribute. This means the
|
||||
user has to manually include the correct encryption algorithm. It should store
|
||||
the list of permitted ciphers in a database and only use those.
|
||||
|
||||
No revocation checking is done on the signer's certificate.
|
||||
|
||||
The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
|
||||
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
|
||||
|
||||
The -no_alt_chains option was added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,104 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-speed,
|
||||
speed - test library performance
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl speed>
|
||||
[B<-help>]
|
||||
[B<-engine id>]
|
||||
[B<-elapsed>]
|
||||
[B<-evp algo>]
|
||||
[B<-decrypt>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-primes num>]
|
||||
[B<-seconds num>]
|
||||
[B<-bytes num>]
|
||||
[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. The global CSPRNG is denoted by
|
||||
the I<rand> algorithm name.
|
||||
|
||||
=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>
|
||||
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<-elapsed>
|
||||
|
||||
When calculating operations- or bytes-per-second, use wall-clock time
|
||||
instead of CPU user time as divisor. It can be useful when testing speed
|
||||
of hardware engines.
|
||||
|
||||
=item B<-evp algo>
|
||||
|
||||
Use the specified cipher or message digest algorithm via the EVP interface.
|
||||
If B<algo> is an AEAD cipher, then you can pass <-aead> to benchmark a
|
||||
TLS-like sequence. And if B<algo> is a multi-buffer capable cipher, e.g.
|
||||
aes-128-cbc-hmac-sha1, then B<-mb> will time multi-buffer operation.
|
||||
|
||||
=item B<-decrypt>
|
||||
|
||||
Time the decryption instead of encryption. Affects only the EVP testing.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-primes num>
|
||||
|
||||
Generate a B<num>-prime RSA key and use it to run the benchmarks. This option
|
||||
is only effective if RSA algorithm is specified to test.
|
||||
|
||||
=item B<-seconds num>
|
||||
|
||||
Run benchmarks for B<num> seconds.
|
||||
|
||||
=item B<-bytes num>
|
||||
|
||||
Run benchmarks on B<num>-byte buffers. Affects ciphers, digests and the CSPRNG.
|
||||
|
||||
=item B<[zero or more test algorithms]>
|
||||
|
||||
If any options are given, B<speed> tests those algorithms, otherwise a
|
||||
pre-compiled grand selection is tested.
|
||||
|
||||
=back
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 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
|
||||
@@ -0,0 +1,155 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-spkac,
|
||||
spkac - SPKAC printing and generating utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<spkac>
|
||||
[B<-help>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-key keyfile>]
|
||||
[B<-keyform PEM|DER|ENGINE>]
|
||||
[B<-passin arg>]
|
||||
[B<-challenge string>]
|
||||
[B<-pubkey>]
|
||||
[B<-spkac spkacname>]
|
||||
[B<-spksect section>]
|
||||
[B<-noout>]
|
||||
[B<-verify>]
|
||||
[B<-engine id>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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 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
|
||||
option is not specified. Ignored if the B<-key> option is used.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
Specifies the output filename to write to or standard output by
|
||||
default.
|
||||
|
||||
=item B<-key keyfile>
|
||||
|
||||
Create an SPKAC file using the private key in B<keyfile>. The
|
||||
B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
|
||||
present.
|
||||
|
||||
=item B<-keyform PEM|DER|ENGINE>
|
||||
|
||||
Whether the key format is PEM, DER, or an engine-backed key.
|
||||
The default is PEM.
|
||||
|
||||
=item B<-passin password>
|
||||
|
||||
The input file password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-challenge string>
|
||||
|
||||
Specifies the challenge string if an SPKAC is being created.
|
||||
|
||||
=item B<-spkac spkacname>
|
||||
|
||||
Allows an alternative name form the variable containing the
|
||||
SPKAC. The default is "SPKAC". This option affects both
|
||||
generated and input SPKAC files.
|
||||
|
||||
=item B<-spksect section>
|
||||
|
||||
Allows an alternative name form the section containing the
|
||||
SPKAC. The default is the default section.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
Don't output the text version of the SPKAC (not used if an
|
||||
SPKAC is being created).
|
||||
|
||||
=item B<-pubkey>
|
||||
|
||||
Output the public key of an SPKAC (not used if an SPKAC is
|
||||
being created).
|
||||
|
||||
=item B<-verify>
|
||||
|
||||
Verifies the digital signature on the supplied SPKAC.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<spkac>
|
||||
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 EXAMPLES
|
||||
|
||||
Print out the contents of an SPKAC:
|
||||
|
||||
openssl spkac -in spkac.cnf
|
||||
|
||||
Verify the signature of an SPKAC:
|
||||
|
||||
openssl spkac -in spkac.cnf -noout -verify
|
||||
|
||||
Create an SPKAC using the challenge string "hello":
|
||||
|
||||
openssl spkac -key key.pem -challenge hello -out spkac.cnf
|
||||
|
||||
Example of an SPKAC, (long lines split up for clarity):
|
||||
|
||||
SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA\
|
||||
1cCoq2Wa3Ixs47uI7FPVwHVIPDx5yso105Y6zpozam135a\
|
||||
8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03uPFoQIDAQAB\
|
||||
FgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJ\
|
||||
h1bEIYuc2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnD\
|
||||
dq+NQ3F+X4deMx9AaEglZtULwV4=
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A created SPKAC with suitable DN components appended can be fed into
|
||||
the B<ca> utility.
|
||||
|
||||
SPKACs are typically generated by Netscape when a form is submitted
|
||||
containing the B<KEYGEN> tag as part of the certificate enrollment
|
||||
process.
|
||||
|
||||
The challenge string permits a primitive form of proof of possession
|
||||
of private key. By checking the SPKAC signature and a random challenge
|
||||
string some guarantee is given that the user knows the private key
|
||||
corresponding to the public key being certified. This is important in
|
||||
some applications. Without this it is possible for a previous SPKAC
|
||||
to be used in a "replay attack".
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ca(1)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,73 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-srp,
|
||||
srp - maintain SRP password file
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl srp>
|
||||
[B<-help>]
|
||||
[B<-verbose>]
|
||||
[B<-add>]
|
||||
[B<-modify>]
|
||||
[B<-delete>]
|
||||
[B<-list>]
|
||||
[B<-name section>]
|
||||
[B<-config file>]
|
||||
[B<-srpvfile file>]
|
||||
[B<-gn identifier>]
|
||||
[B<-userinfo text...>]
|
||||
[B<-passin arg>]
|
||||
[B<-passout arg>]
|
||||
[I<user...>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<srp> command is user to maintain an SRP (secure remote password)
|
||||
file.
|
||||
At most one of the B<-add>, B<-modify>, B<-delete>, and B<-list> options
|
||||
can be specified.
|
||||
These options take zero or more usernames as parameters and perform the
|
||||
appropriate operation on the SRP file.
|
||||
For B<-list>, if no B<user> is given then all users are displayed.
|
||||
|
||||
The configuration file to use, and the section within the file, can be
|
||||
specified with the B<-config> and B<-name> flags, respectively.
|
||||
If the config file is not specified, the B<-srpvfile> can be used to
|
||||
just specify the file to operate on.
|
||||
|
||||
The B<-userinfo> option specifies additional information to add when
|
||||
adding or modifying a user.
|
||||
|
||||
The B<-gn> flag specifies the B<g> and B<N> values, using one of
|
||||
the strengths defined in IETF RFC 5054.
|
||||
|
||||
The B<-passin> and B<-passout> arguments are parsed as described in
|
||||
the L<openssl(1)> command.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item [B<-help>]
|
||||
|
||||
Display an option summary.
|
||||
|
||||
=item [B<-verbose>]
|
||||
|
||||
Generate verbose output while processing.
|
||||
|
||||
=back
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 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
|
||||
@@ -0,0 +1,133 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-storeutl,
|
||||
storeutl - STORE utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<storeutl>
|
||||
[B<-help>]
|
||||
[B<-out file>]
|
||||
[B<-noout>]
|
||||
[B<-passin arg>]
|
||||
[B<-text arg>]
|
||||
[B<-engine id>]
|
||||
[B<-r>]
|
||||
[B<-certs>]
|
||||
[B<-keys>]
|
||||
[B<-crls>]
|
||||
[B<-subject arg>]
|
||||
[B<-issuer arg>]
|
||||
[B<-serial arg>]
|
||||
[B<-alias arg>]
|
||||
[B<-fingerprint arg>]
|
||||
[B<-I<digest>>]
|
||||
B<uri> ...
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<storeutl> command can be used to display the contents (after decryption
|
||||
as the case may be) fetched from the given URIs.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Print out a usage message.
|
||||
|
||||
=item B<-out filename>
|
||||
|
||||
specifies the output filename to write to or standard output by
|
||||
default.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
this option prevents output of the PEM data.
|
||||
|
||||
=item B<-passin arg>
|
||||
|
||||
the key password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-text>
|
||||
|
||||
Prints out the objects in text form, similarly to the B<-text> output from
|
||||
B<openssl x509>, B<openssl pkey>, etc.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
specifying an engine (by its unique B<id> string) will cause B<storeutl>
|
||||
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<-r>
|
||||
|
||||
Fetch objects recursively when possible.
|
||||
|
||||
=item B<-certs>
|
||||
|
||||
=item B<-keys>
|
||||
|
||||
=item B<-crls>
|
||||
|
||||
Only select the certificates, keys or CRLs from the given URI.
|
||||
However, if this URI would return a set of names (URIs), those are always
|
||||
returned.
|
||||
|
||||
=item B<-subject arg>
|
||||
|
||||
Search for an object having the subject name B<arg>.
|
||||
The arg must be formatted as I</type0=value0/type1=value1/type2=...>.
|
||||
Keyword characters may be escaped by \ (backslash), and whitespace is retained.
|
||||
Empty values are permitted but are ignored for the search. That is,
|
||||
a search with an empty value will have the same effect as not specifying
|
||||
the type at all.
|
||||
|
||||
=item B<-issuer arg>
|
||||
|
||||
=item B<-serial arg>
|
||||
|
||||
Search for an object having the given issuer name and serial number.
|
||||
These two options I<must> be used together.
|
||||
The issuer arg must be formatted as I</type0=value0/type1=value1/type2=...>,
|
||||
characters may be escaped by \ (backslash), no spaces are skipped.
|
||||
The serial arg may be specified as a decimal value or a hex value if preceded
|
||||
by B<0x>.
|
||||
|
||||
=item B<-alias arg>
|
||||
|
||||
Search for an object having the given alias.
|
||||
|
||||
=item B<-fingerprint arg>
|
||||
|
||||
Search for an object having the given fingerprint.
|
||||
|
||||
=item B<-I<digest>>
|
||||
|
||||
The digest that was used to compute the fingerprint given with B<-fingerprint>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<openssl(1)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The B<openssl> B<storeutl> app was added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2021 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
|
||||
@@ -0,0 +1,675 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-ts,
|
||||
ts - Time Stamping Authority tool (client/server)
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<ts>
|
||||
B<-query>
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-config> configfile]
|
||||
[B<-data> file_to_hash]
|
||||
[B<-digest> digest_bytes]
|
||||
[B<-I<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<-reply>
|
||||
[B<-config> configfile]
|
||||
[B<-section> tsa_section]
|
||||
[B<-queryfile> request.tsq]
|
||||
[B<-passin> password_src]
|
||||
[B<-signer> tsa_cert.pem]
|
||||
[B<-inkey> file_or_id]
|
||||
[B<-I<digest>>]
|
||||
[B<-chain> certs_file.pem]
|
||||
[B<-tspolicy> object_id]
|
||||
[B<-in> response.tsr]
|
||||
[B<-token_in>]
|
||||
[B<-out> response.tsr]
|
||||
[B<-token_out>]
|
||||
[B<-text>]
|
||||
[B<-engine> id]
|
||||
|
||||
B<openssl> B<ts>
|
||||
B<-verify>
|
||||
[B<-data> file_to_hash]
|
||||
[B<-digest> digest_bytes]
|
||||
[B<-queryfile> request.tsq]
|
||||
[B<-in> response.tsr]
|
||||
[B<-token_in>]
|
||||
[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
|
||||
|
||||
The B<ts> command is a basic Time Stamping Authority (TSA) client and server
|
||||
application as specified in RFC 3161 (Time-Stamp Protocol, TSP). A
|
||||
TSA can be part of a PKI deployment and its role is to provide long
|
||||
term proof of the existence of a certain datum before a particular
|
||||
time. Here is a brief description of the protocol:
|
||||
|
||||
=over 4
|
||||
|
||||
=item 1.
|
||||
|
||||
The TSA client computes a one-way hash value for a data file and sends
|
||||
the hash to the TSA.
|
||||
|
||||
=item 2.
|
||||
|
||||
The TSA attaches the current date and time to the received hash value,
|
||||
signs them and sends the timestamp token back to the client. By
|
||||
creating this token the TSA certifies the existence of the original
|
||||
data file at the time of response generation.
|
||||
|
||||
=item 3.
|
||||
|
||||
The TSA client receives the timestamp token and verifies the
|
||||
signature on it. It also checks if the token contains the same hash
|
||||
value that it had sent to the TSA.
|
||||
|
||||
=back
|
||||
|
||||
There is one DER encoded protocol data unit defined for transporting
|
||||
a timestamp request to the TSA and one for sending the timestamp response
|
||||
back to the client. The B<ts> command has three main functions:
|
||||
creating a timestamp request based on a data file,
|
||||
creating a timestamp response based on a request, verifying if a
|
||||
response corresponds to a particular request or a data file.
|
||||
|
||||
There is no support for sending the requests/responses automatically
|
||||
over HTTP or TCP yet as suggested in RFC 3161. The users must send the
|
||||
requests either by ftp or e-mail.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=head2 Time Stamp Request generation
|
||||
|
||||
The B<-query> switch can be used for creating and printing a timestamp
|
||||
request with the following options:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-config> configfile
|
||||
|
||||
The configuration file to use.
|
||||
Optional; for a description of the default value,
|
||||
see L<openssl(1)/COMMAND SUMMARY>.
|
||||
|
||||
=item B<-data> file_to_hash
|
||||
|
||||
The data file for which the timestamp request needs to be
|
||||
created. stdin is the default if neither the B<-data> nor the B<-digest>
|
||||
parameter is specified. (Optional)
|
||||
|
||||
=item B<-digest> digest_bytes
|
||||
|
||||
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
|
||||
in use. (Optional)
|
||||
|
||||
=item B<-I<digest>>
|
||||
|
||||
The message digest to apply to the data file.
|
||||
Any digest supported by the OpenSSL B<dgst> command can be used.
|
||||
The default is SHA-1. (Optional)
|
||||
|
||||
=item B<-tspolicy> object_id
|
||||
|
||||
The policy that the client expects the TSA to use for creating the
|
||||
timestamp token. Either the dotted OID notation or OID names defined
|
||||
in the config file can be used. If no policy is requested the TSA will
|
||||
use its own default policy. (Optional)
|
||||
|
||||
=item B<-no_nonce>
|
||||
|
||||
No nonce is specified in the request if this option is
|
||||
given. Otherwise a 64 bit long pseudo-random none is
|
||||
included in the request. It is recommended to use nonce to
|
||||
protect against replay-attacks. (Optional)
|
||||
|
||||
=item B<-cert>
|
||||
|
||||
The TSA is expected to include its signing certificate in the
|
||||
response. (Optional)
|
||||
|
||||
=item B<-in> request.tsq
|
||||
|
||||
This option specifies a previously created timestamp request in DER
|
||||
format that will be printed into the output file. Useful when you need
|
||||
to examine the content of a request in human-readable
|
||||
format. (Optional)
|
||||
|
||||
=item B<-out> request.tsq
|
||||
|
||||
Name of the output file to which the request will be written. Default
|
||||
is stdout. (Optional)
|
||||
|
||||
=item B<-text>
|
||||
|
||||
If this option is specified the output is human-readable text format
|
||||
instead of DER. (Optional)
|
||||
|
||||
=back
|
||||
|
||||
=head2 Time Stamp Response generation
|
||||
|
||||
A timestamp response (TimeStampResp) consists of a response status
|
||||
and the timestamp token itself (ContentInfo), if the token generation was
|
||||
successful. The B<-reply> command is for creating a timestamp
|
||||
response or timestamp token based on a request and printing the
|
||||
response/token in human-readable format. If B<-token_out> is not
|
||||
specified the output is always a timestamp response (TimeStampResp),
|
||||
otherwise it is a timestamp token (ContentInfo).
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-config> configfile
|
||||
|
||||
The configuration file to use.
|
||||
Optional; for a description of the default value,
|
||||
see L<openssl(1)/COMMAND SUMMARY>.
|
||||
See B<CONFIGURATION FILE OPTIONS> for configurable variables.
|
||||
|
||||
=item B<-section> tsa_section
|
||||
|
||||
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)
|
||||
|
||||
=item B<-queryfile> request.tsq
|
||||
|
||||
The name of the file containing a DER encoded timestamp request. (Optional)
|
||||
|
||||
=item B<-passin> password_src
|
||||
|
||||
Specifies the password source for the private key of the TSA. See
|
||||
L<openssl(1)/Pass Phrase Options>. (Optional)
|
||||
|
||||
=item B<-signer> tsa_cert.pem
|
||||
|
||||
The signer certificate of the TSA in PEM format. The TSA signing
|
||||
certificate must have exactly one extended key usage assigned to it:
|
||||
timeStamping. The extended key usage must also be critical, otherwise
|
||||
the certificate is going to be refused. Overrides the B<signer_cert>
|
||||
variable of the config file. (Optional)
|
||||
|
||||
=item B<-inkey> file_or_id
|
||||
|
||||
The signer private key of the TSA in PEM format. Overrides the
|
||||
B<signer_key> config file option. (Optional)
|
||||
If no engine is used, the argument is taken as a file; if an engine is
|
||||
specified, the argument is given to the engine as a key identifier.
|
||||
|
||||
=item B<-I<digest>>
|
||||
|
||||
Signing digest to use. Overrides the B<signer_digest> config file
|
||||
option. (Mandatory unless specified in the config file)
|
||||
|
||||
=item B<-chain> certs_file.pem
|
||||
|
||||
The collection of certificates in PEM format that will all
|
||||
be included in the response in addition to the signer certificate if
|
||||
the B<-cert> option was used for the request. This file is supposed to
|
||||
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<-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
|
||||
either in dotted notation or with its name. Overrides the
|
||||
B<default_policy> config file option. (Optional)
|
||||
|
||||
=item B<-in> response.tsr
|
||||
|
||||
Specifies a previously created timestamp response or timestamp token
|
||||
(if B<-token_in> is also specified) in DER format that will be written
|
||||
to the output file. This option does not require a request, it is
|
||||
useful e.g. when you need to examine the content of a response or
|
||||
token or you want to extract the timestamp token from a response. If
|
||||
the input is a token and the output is a timestamp response a default
|
||||
'granted' status info is added to the token. (Optional)
|
||||
|
||||
=item B<-token_in>
|
||||
|
||||
This flag can be used together with the B<-in> option and indicates
|
||||
that the input is a DER encoded timestamp token (ContentInfo) instead
|
||||
of a timestamp response (TimeStampResp). (Optional)
|
||||
|
||||
=item B<-out> response.tsr
|
||||
|
||||
The response is written to this file. The format and content of the
|
||||
file depends on other options (see B<-text>, B<-token_out>). The default is
|
||||
stdout. (Optional)
|
||||
|
||||
=item B<-token_out>
|
||||
|
||||
The output is a timestamp token (ContentInfo) instead of timestamp
|
||||
response (TimeStampResp). (Optional)
|
||||
|
||||
=item B<-text>
|
||||
|
||||
If this option is specified the output is human-readable text format
|
||||
instead of DER. (Optional)
|
||||
|
||||
=item B<-engine> id
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<ts>
|
||||
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. Default is builtin. (Optional)
|
||||
|
||||
=back
|
||||
|
||||
=head2 Time Stamp Response verification
|
||||
|
||||
The B<-verify> command is for verifying if a timestamp response or
|
||||
timestamp token is valid and matches a particular timestamp request or
|
||||
data file. The B<-verify> command does not use the configuration file.
|
||||
|
||||
=over 4
|
||||
|
||||
=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.
|
||||
The B<-digest> and B<-queryfile> options must not be specified with this one.
|
||||
(Optional)
|
||||
|
||||
=item B<-digest> digest_bytes
|
||||
|
||||
The response or token must be verified against the message digest specified
|
||||
with this option. The number of bytes must match the message digest algorithm
|
||||
specified in the token. The B<-data> and B<-queryfile> options must not be
|
||||
specified with this one. (Optional)
|
||||
|
||||
=item B<-queryfile> request.tsq
|
||||
|
||||
The original timestamp request in DER format. The B<-data> and B<-digest>
|
||||
options must not be specified with this one. (Optional)
|
||||
|
||||
=item B<-in> response.tsr
|
||||
|
||||
The timestamp response that needs to be verified in DER format. (Mandatory)
|
||||
|
||||
=item B<-token_in>
|
||||
|
||||
This flag can be used together with the B<-in> option and indicates
|
||||
that the input is a DER encoded timestamp token (ContentInfo) instead
|
||||
of a timestamp response (TimeStampResp). (Optional)
|
||||
|
||||
=item B<-CApath> trusted_cert_path
|
||||
|
||||
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)> for additional details. Either this option
|
||||
or B<-CApath> must be specified.
|
||||
(Optional)
|
||||
|
||||
=item B<-untrusted> cert_file.pem
|
||||
|
||||
Set of additional untrusted certificates in PEM format which may be
|
||||
needed when building the certificate chain for the TSA's signing
|
||||
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.
|
||||
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
|
||||
config file for its operation.
|
||||
|
||||
When there is a command line switch equivalent of a variable the
|
||||
switch always overrides the settings in the config file.
|
||||
|
||||
=over 4
|
||||
|
||||
=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
|
||||
section can be overridden with the B<-section> command line switch. (Optional)
|
||||
|
||||
=item B<oid_file>
|
||||
|
||||
See L<ca(1)> for description. (Optional)
|
||||
|
||||
=item B<oid_section>
|
||||
|
||||
See L<ca(1)> for description. (Optional)
|
||||
|
||||
=item B<RANDFILE>
|
||||
|
||||
See L<ca(1)> for description. (Optional)
|
||||
|
||||
=item B<serial>
|
||||
|
||||
The name of the file containing the hexadecimal serial number of the
|
||||
last timestamp response created. This number is incremented by 1 for
|
||||
each response. If the file does not exist at the time of response
|
||||
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).
|
||||
(Optional)
|
||||
|
||||
=item B<signer_cert>
|
||||
|
||||
TSA signing certificate in PEM format. The same as the B<-signer>
|
||||
command line option. (Optional)
|
||||
|
||||
=item B<certs>
|
||||
|
||||
A file containing a set of PEM encoded certificates that need to be
|
||||
included in the response. The same as the B<-chain> command line
|
||||
option. (Optional)
|
||||
|
||||
=item B<signer_key>
|
||||
|
||||
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<-I<digest>> command line option. (Mandatory unless specified on the command
|
||||
line)
|
||||
|
||||
=item B<default_policy>
|
||||
|
||||
The default policy to use when the request does not mandate any
|
||||
policy. The same as the B<-tspolicy> command line option. (Optional)
|
||||
|
||||
=item B<other_policies>
|
||||
|
||||
Comma separated list of policies that are also acceptable by the TSA
|
||||
and used only if the request explicitly specifies one of them. (Optional)
|
||||
|
||||
=item B<digests>
|
||||
|
||||
The list of message digest algorithms that the TSA accepts. At least
|
||||
one algorithm must be specified. (Mandatory)
|
||||
|
||||
=item B<accuracy>
|
||||
|
||||
The accuracy of the time source of the TSA in seconds, milliseconds
|
||||
and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
|
||||
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
|
||||
seconds, that need to be included in the time field. The trailing zeros
|
||||
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.
|
||||
The maximum value is 6, default is 0.
|
||||
(Optional)
|
||||
|
||||
=item B<ordering>
|
||||
|
||||
If this option is yes the responses generated by this TSA can always
|
||||
be ordered, even if the time difference between two responses is less
|
||||
than the sum of their accuracies. Default is no. (Optional)
|
||||
|
||||
=item B<tsa_name>
|
||||
|
||||
Set this option to yes if the subject name of the TSA must be included in
|
||||
the TSA name field of the response. Default is no. (Optional)
|
||||
|
||||
=item B<ess_cert_id_chain>
|
||||
|
||||
The SignedData objects created by the TSA always contain the
|
||||
certificate identifier of the signing certificate in a signed
|
||||
attribute (see RFC 2634, Enhanced Security Services). If this option
|
||||
is set to yes and either the B<certs> variable or the B<-chain> option
|
||||
is specified then the certificate identifiers of the chain will also
|
||||
be included in the SigningCertificate signed attribute. If this
|
||||
variable is set to no, only the signing certificate identifier is
|
||||
included. Default is no. (Optional)
|
||||
|
||||
=item B<ess_cert_id_alg>
|
||||
|
||||
This option specifies the hash function to be used to calculate the TSA's
|
||||
public key certificate identifier. Default is sha1. (Optional)
|
||||
|
||||
=back
|
||||
|
||||
=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.
|
||||
|
||||
=head2 Time Stamp Request
|
||||
|
||||
To create a timestamp 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
|
||||
|
||||
To create a similar timestamp request with specifying the message imprint
|
||||
explicitly:
|
||||
|
||||
openssl 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
|
||||
|
||||
To create a timestamp 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 \
|
||||
-tspolicy tsa_policy1 -cert -out design2.tsq
|
||||
|
||||
=head2 Time Stamp Response
|
||||
|
||||
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 this line to the
|
||||
user certificate section of the config file to generate a proper certificate;
|
||||
|
||||
extendedKeyUsage = critical,timeStamping
|
||||
|
||||
See L<req(1)>, L<ca(1)>, and 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 timestamp response for a request:
|
||||
|
||||
openssl 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
|
||||
|
||||
To print a timestamp reply to stdout in human readable format:
|
||||
|
||||
openssl ts -reply -in design1.tsr -text
|
||||
|
||||
To create a timestamp token instead of timestamp response:
|
||||
|
||||
openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
|
||||
|
||||
To print a timestamp token to stdout in human readable format:
|
||||
|
||||
openssl ts -reply -in design1_token.der -token_in -text -token_out
|
||||
|
||||
To extract the timestamp token from a response:
|
||||
|
||||
openssl ts -reply -in design1.tsr -out design1_token.der -token_out
|
||||
|
||||
To add 'granted' status info to a timestamp token thereby creating a
|
||||
valid response:
|
||||
|
||||
openssl ts -reply -in design1_token.der -token_in -out design1.tsr
|
||||
|
||||
=head2 Time Stamp Verification
|
||||
|
||||
To verify a timestamp reply against a request:
|
||||
|
||||
openssl ts -verify -queryfile design1.tsq -in design1.tsr \
|
||||
-CAfile cacert.pem -untrusted tsacert.pem
|
||||
|
||||
To verify a timestamp reply that includes the certificate chain:
|
||||
|
||||
openssl ts -verify -queryfile design2.tsq -in design2.tsr \
|
||||
-CAfile cacert.pem
|
||||
|
||||
To verify a timestamp token against the original data file:
|
||||
openssl ts -verify -data design2.txt -in design2.tsr \
|
||||
-CAfile cacert.pem
|
||||
|
||||
To verify a timestamp token against a message imprint:
|
||||
openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
|
||||
-in design2.tsr -CAfile cacert.pem
|
||||
|
||||
You could also look at the 'test' directory for more examples.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
=for comment foreign manuals: procmail(1), perl(1)
|
||||
|
||||
=over 2
|
||||
|
||||
=item *
|
||||
|
||||
No support for timestamps over SMTP, though it is quite easy
|
||||
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)>. 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)> is trying to create a timestamp
|
||||
response at the same time. This is not an issue when using the apache
|
||||
server module, it does proper locking.
|
||||
|
||||
=item *
|
||||
|
||||
Look for the FIXME word in the source files.
|
||||
|
||||
=item *
|
||||
|
||||
The source code should really be reviewed by somebody else, too.
|
||||
|
||||
=item *
|
||||
|
||||
More testing is needed, I have done only some basic tests (see
|
||||
test/testtsa).
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<tsget(1)>, L<openssl(1)>, L<req(1)>,
|
||||
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
|
||||
L<config(5)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2006-2021 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
|
||||
@@ -0,0 +1,202 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-tsget,
|
||||
tsget - Time Stamping HTTP/HTTPS client
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<tsget>
|
||||
B<-h> server_url
|
||||
[B<-e> extension]
|
||||
[B<-o> output]
|
||||
[B<-v>]
|
||||
[B<-d>]
|
||||
[B<-k> private_key.pem]
|
||||
[B<-p> key_password]
|
||||
[B<-c> client_cert.pem]
|
||||
[B<-C> CA_certs.pem]
|
||||
[B<-P> CA_path]
|
||||
[B<-r> file:file...]
|
||||
[B<-g> EGD_socket]
|
||||
[request]...
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<tsget> command can be used for sending a timestamp request, as
|
||||
specified in B<RFC 3161>, to a timestamp server over HTTP or HTTPS and storing
|
||||
the timestamp 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
|
||||
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 timestamp 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
|
||||
|
||||
...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.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-h> server_url
|
||||
|
||||
The URL of the HTTP/HTTPS server listening for timestamp requests.
|
||||
|
||||
=item B<-e> extension
|
||||
|
||||
If the B<-o> option is not given this argument specifies the extension of the
|
||||
output files. The base name of the output file will be the same as those of
|
||||
the input files. Default extension is '.tsr'. (Optional)
|
||||
|
||||
=item B<-o> output
|
||||
|
||||
This option can be specified only when just one request is sent to the
|
||||
server. The timestamp response will be written to the given output file. '-'
|
||||
means standard output. In case of multiple timestamp requests or the absence
|
||||
of this argument the names of the output files will be derived from the names
|
||||
of the input files and the default or specified extension argument. (Optional)
|
||||
|
||||
=item B<-v>
|
||||
|
||||
The name of the currently processed request is printed on standard
|
||||
error. (Optional)
|
||||
|
||||
=item B<-d>
|
||||
|
||||
Switches on verbose mode for the underlying B<curl> library. You can see
|
||||
detailed debug messages for the connection. (Optional)
|
||||
|
||||
=item B<-k> private_key.pem
|
||||
|
||||
(HTTPS) In case of certificate-based client authentication over HTTPS
|
||||
<private_key.pem> must contain the private key of the user. The private key
|
||||
file can optionally be protected by a passphrase. The B<-c> option must also
|
||||
be specified. (Optional)
|
||||
|
||||
=item B<-p> key_password
|
||||
|
||||
(HTTPS) Specifies the passphrase for the private key specified by the B<-k>
|
||||
argument. If this option is omitted and the key is passphrase protected B<tsget>
|
||||
will ask for it. (Optional)
|
||||
|
||||
=item B<-c> client_cert.pem
|
||||
|
||||
(HTTPS) In case of certificate-based client authentication over HTTPS
|
||||
<client_cert.pem> must contain the X.509 certificate of the user. The B<-k>
|
||||
option must also be specified. If this option is not specified no
|
||||
certificate-based client authentication will take place. (Optional)
|
||||
|
||||
=item B<-C> CA_certs.pem
|
||||
|
||||
(HTTPS) The trusted CA certificate store. The certificate chain of the peer's
|
||||
certificate must include one of the CA certificates specified in this file.
|
||||
Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional)
|
||||
|
||||
=item B<-P> CA_path
|
||||
|
||||
(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
|
||||
HTTPS. (Optional)
|
||||
|
||||
=item B<-rand> file:file...
|
||||
|
||||
The files containing random data for seeding the random number
|
||||
generator. Multiple files can be specified, the separator is B<;> for
|
||||
MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
|
||||
|
||||
=item B<-g> EGD_socket
|
||||
|
||||
The name of an EGD socket to get random data from. (Optional)
|
||||
|
||||
=item [request]...
|
||||
|
||||
List of files containing B<RFC 3161> DER-encoded timestamp requests. If no
|
||||
requests are specified only one request will be sent to the server and it will be
|
||||
read from the standard input. (Optional)
|
||||
|
||||
=back
|
||||
|
||||
=head1 ENVIRONMENT VARIABLES
|
||||
|
||||
The B<TSGET> environment variable can optionally contain default
|
||||
arguments. The content of this variable is added to the list of command line
|
||||
arguments.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid
|
||||
timestamp 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 timestamp response for file1.tsq over HTTP, output is written to
|
||||
file1.tsr:
|
||||
|
||||
tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq
|
||||
|
||||
Get a timestamp 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
|
||||
|
||||
Create a timestamp 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
|
||||
|
||||
Get a timestamp response for file1.tsq over HTTPS without client
|
||||
authentication:
|
||||
|
||||
tsget -h https://tsa.opentsa.org:8443/tsa \
|
||||
-C cacerts.pem file1.tsq
|
||||
|
||||
Get a timestamp 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
|
||||
|
||||
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'
|
||||
export TSGET
|
||||
tsget file1.tsq
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
=for comment foreign manuals: curl(1)
|
||||
|
||||
L<openssl(1)>, L<ts(1)>, L<curl(1)>,
|
||||
B<RFC 3161>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2006-2020 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
|
||||
@@ -0,0 +1,786 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-verify,
|
||||
verify - Utility to verify certificates
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<verify>
|
||||
[B<-help>]
|
||||
[B<-CAfile file>]
|
||||
[B<-CApath directory>]
|
||||
[B<-no-CAfile>]
|
||||
[B<-no-CApath>]
|
||||
[B<-allow_proxy_certs>]
|
||||
[B<-attime timestamp>]
|
||||
[B<-check_ss_sig>]
|
||||
[B<-CRLfile file>]
|
||||
[B<-crl_download>]
|
||||
[B<-crl_check>]
|
||||
[B<-crl_check_all>]
|
||||
[B<-engine id>]
|
||||
[B<-explicit_policy>]
|
||||
[B<-extended_crl>]
|
||||
[B<-ignore_critical>]
|
||||
[B<-inhibit_any>]
|
||||
[B<-inhibit_map>]
|
||||
[B<-nameopt option>]
|
||||
[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<-untrusted file>]
|
||||
[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 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.
|
||||
|
||||
=item B<-CApath directory>
|
||||
|
||||
A directory of trusted certificates. The certificates should have names
|
||||
of the form: hash.0 or have symbolic links to them of this
|
||||
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<-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<-allow_proxy_certs>
|
||||
|
||||
Allow the verification of proxy certificates.
|
||||
|
||||
=item B<-attime timestamp>
|
||||
|
||||
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).
|
||||
|
||||
=item B<-check_ss_sig>
|
||||
|
||||
Verify the signature of
|
||||
the last certificate in a chain if the certificate is supposedly self-signed.
|
||||
This is prohibited and will result in an error if it is a non-conforming CA
|
||||
certificate with key usage restrictions not including the keyCertSign bit.
|
||||
This verification is disabled by default because it doesn't add any security.
|
||||
|
||||
=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>.
|
||||
|
||||
=item B<-crl_download>
|
||||
|
||||
Attempt to download CRL information for this certificate.
|
||||
|
||||
=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<-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.
|
||||
|
||||
=item B<-explicit_policy>
|
||||
|
||||
Set policy variable require-explicit-policy (see RFC5280).
|
||||
|
||||
=item B<-extended_crl>
|
||||
|
||||
Enable extended CRL features such as indirect CRLs and alternate CRL
|
||||
signing keys.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-inhibit_any>
|
||||
|
||||
Set policy variable inhibit-any-policy (see RFC5280).
|
||||
|
||||
=item B<-inhibit_map>
|
||||
|
||||
Set policy variable inhibit-policy-mapping (see RFC5280).
|
||||
|
||||
=item B<-nameopt option>
|
||||
|
||||
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)> manual page for details.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-policy_check>
|
||||
|
||||
Enables certificate policy processing.
|
||||
|
||||
=item B<-policy_print>
|
||||
|
||||
Print out diagnostics related to policy processing.
|
||||
|
||||
=item B<-purpose purpose>
|
||||
|
||||
The intended use for the certificate. If this option is not specified,
|
||||
B<verify> will not consider certificate purpose during chain verification.
|
||||
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<-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.
|
||||
|
||||
=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 OpenSSL 1.1.0 this option is on by default and cannot be disabled.
|
||||
|
||||
=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 OpenSSL 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 OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
|
||||
effect.
|
||||
|
||||
=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>.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-use_deltas>
|
||||
|
||||
Enable support for delta CRLs.
|
||||
|
||||
=item B<-verbose>
|
||||
|
||||
Print extra information about the operations being performed.
|
||||
|
||||
=item B<-auth_level level>
|
||||
|
||||
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.
|
||||
|
||||
=item B<-verify_depth num>
|
||||
|
||||
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<-verify_email email>
|
||||
|
||||
Verify if the B<email> matches the email address in Subject Alternative Name or
|
||||
the email in the subject Distinguished Name.
|
||||
|
||||
=item B<-verify_hostname hostname>
|
||||
|
||||
Verify if the B<hostname> matches DNS name in Subject Alternative Name or
|
||||
Common Name in the subject certificate.
|
||||
|
||||
=item B<-verify_ip ip>
|
||||
|
||||
Verify if the B<ip> matches the IP address in Subject Alternative Name of
|
||||
the subject certificate.
|
||||
|
||||
=item B<-verify_name name>
|
||||
|
||||
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 OpenSSL 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<-x509_strict>
|
||||
|
||||
For strict X.509 compliance, disable non-compliant workarounds for broken
|
||||
certificates.
|
||||
|
||||
=item B<-show_chain>
|
||||
|
||||
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".
|
||||
|
||||
=item B<->
|
||||
|
||||
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.
|
||||
|
||||
=back
|
||||
|
||||
=head1 VERIFY OPERATION
|
||||
|
||||
The B<verify> program uses the same functions as the internal SSL and S/MIME
|
||||
verification, therefore, this description applies to these verify operations
|
||||
too.
|
||||
|
||||
There is one crucial difference between the verify operations performed
|
||||
by the B<verify> program: wherever possible an attempt is made to continue
|
||||
after an error whereas normally the verify operation would halt on the
|
||||
first error. This allows all the problems with a certificate chain to be
|
||||
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.
|
||||
|
||||
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
|
||||
is always looked up in the trusted certificate list: if the certificate to
|
||||
verify is a root certificate then an exact match must be found in the trusted
|
||||
list.
|
||||
|
||||
The second operation is to check every untrusted certificate's extensions for
|
||||
consistency with the supplied purpose. If the B<-purpose> option is not included
|
||||
then no checks are done. The supplied or "leaf" certificate must have extensions
|
||||
compatible with the supplied purpose and all other certificates must also be valid
|
||||
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 OpenSSL, 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.
|
||||
For each element in the chain, including the root CA certificate,
|
||||
the validity period as specified by the C<notBefore> and C<notAfter> fields
|
||||
is checked against the current system time.
|
||||
The B<-attime> flag may be used to use a reference time other than "now."
|
||||
The certificate signature is checked as well
|
||||
(except for the signature of the typically self-signed root CA certificate,
|
||||
which is verified only if the B<-check_ss_sig> option is given).
|
||||
|
||||
If all operations complete successfully then certificate is considered valid. If
|
||||
any operation fails then the certificate is not valid.
|
||||
|
||||
=head1 DIAGNOSTICS
|
||||
|
||||
When a verify operation fails the output messages can be somewhat cryptic. The
|
||||
general form of the error message is:
|
||||
|
||||
server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
|
||||
error 24 at 1 depth lookup:invalid CA certificate
|
||||
|
||||
The first line contains the name of the certificate being verified followed by
|
||||
the subject name of the certificate. The second line contains the error number
|
||||
and the depth. The depth is number of the certificate being verified when a
|
||||
problem was detected starting with zero for the certificate being verified itself
|
||||
then 1 for the CA that signed the certificate and so on. Finally a text version
|
||||
of the error number is presented.
|
||||
|
||||
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<X509_V_OK>
|
||||
|
||||
The operation was successful.
|
||||
|
||||
=item B<X509_V_ERR_UNSPECIFIED>
|
||||
|
||||
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<X509_V_ERR_UNABLE_TO_GET_CRL>
|
||||
|
||||
The CRL of a certificate could not be found.
|
||||
|
||||
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
|
||||
|
||||
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<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
|
||||
|
||||
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<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
|
||||
|
||||
The public key in the certificate SubjectPublicKeyInfo could not be read.
|
||||
|
||||
=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
|
||||
|
||||
The signature of the certificate is invalid.
|
||||
|
||||
=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
|
||||
|
||||
The signature of the certificate is invalid.
|
||||
|
||||
=item B<X509_V_ERR_CERT_NOT_YET_VALID>
|
||||
|
||||
The certificate is not yet valid: the notBefore date is after the
|
||||
current time.
|
||||
|
||||
=item B<X509_V_ERR_CERT_HAS_EXPIRED>
|
||||
|
||||
The certificate has expired: that is the notAfter date is before the
|
||||
current time.
|
||||
|
||||
=item B<X509_V_ERR_CRL_NOT_YET_VALID>
|
||||
|
||||
The CRL is not yet valid.
|
||||
|
||||
=item B<X509_V_ERR_CRL_HAS_EXPIRED>
|
||||
|
||||
The CRL has expired.
|
||||
|
||||
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
|
||||
|
||||
The certificate notBefore field contains an invalid time.
|
||||
|
||||
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
|
||||
|
||||
The certificate notAfter field contains an invalid time.
|
||||
|
||||
=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
|
||||
|
||||
The CRL lastUpdate field contains an invalid time.
|
||||
|
||||
=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
|
||||
|
||||
The CRL nextUpdate field contains an invalid time.
|
||||
|
||||
=item B<X509_V_ERR_OUT_OF_MEM>
|
||||
|
||||
An error occurred trying to allocate memory. This should never happen.
|
||||
|
||||
=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 trusted certificates.
|
||||
|
||||
=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 be found locally.
|
||||
|
||||
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
|
||||
|
||||
The issuer certificate could not be found: this occurs if the issuer
|
||||
certificate of an untrusted certificate cannot be found.
|
||||
|
||||
=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 self signed.
|
||||
|
||||
=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
|
||||
|
||||
The certificate chain length is greater than the supplied maximum
|
||||
depth. Unused.
|
||||
|
||||
=item B<X509_V_ERR_CERT_REVOKED>
|
||||
|
||||
The certificate has been revoked.
|
||||
|
||||
=item B<X509_V_ERR_INVALID_CA>
|
||||
|
||||
A CA certificate is invalid. Either it is not a CA or its extensions
|
||||
are not consistent with the supplied purpose.
|
||||
|
||||
=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
|
||||
|
||||
The basicConstraints pathlength parameter has been exceeded.
|
||||
|
||||
=item B<X509_V_ERR_INVALID_PURPOSE>
|
||||
|
||||
The supplied certificate cannot be used for the specified purpose.
|
||||
|
||||
=item B<X509_V_ERR_CERT_UNTRUSTED>
|
||||
|
||||
The root CA is not marked as trusted for the specified purpose.
|
||||
|
||||
=item B<X509_V_ERR_CERT_REJECTED>
|
||||
|
||||
The root CA is marked to reject the specified purpose.
|
||||
|
||||
=item B<X509_V_ERR_SUBJECT_ISSUER_MISMATCH>
|
||||
|
||||
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
|
||||
B<-issuer_checks> option.
|
||||
|
||||
=item B<X509_V_ERR_AKID_SKID_MISMATCH>
|
||||
|
||||
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
|
||||
B<-issuer_checks> option.
|
||||
|
||||
=item B<X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH>
|
||||
|
||||
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
|
||||
B<-issuer_checks> option.
|
||||
|
||||
=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
|
||||
|
||||
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
|
||||
B<-issuer_checks> option.
|
||||
|
||||
=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
|
||||
|
||||
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)>.
|
||||
|
||||
=item B<X509_V_ERR_EE_KEY_TOO_SMALL>
|
||||
|
||||
EE certificate key too weak.
|
||||
|
||||
=item B<X509_ERR_CA_KEY_TOO_SMALL>
|
||||
|
||||
CA certificate key too weak.
|
||||
|
||||
=item B<X509_ERR_CA_MD_TOO_WEAK>
|
||||
|
||||
CA signature digest algorithm too weak.
|
||||
|
||||
=item B<X509_V_ERR_INVALID_CALL>
|
||||
|
||||
nvalid certificate verification context.
|
||||
|
||||
=item B<X509_V_ERR_STORE_LOOKUP>
|
||||
|
||||
Issuer certificate lookup error.
|
||||
|
||||
=item B<X509_V_ERR_NO_VALID_SCTS>
|
||||
|
||||
Certificate Transparency required, but no valid SCTs found.
|
||||
|
||||
=item B<X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION>
|
||||
|
||||
Proxy subject name violation.
|
||||
|
||||
=item B<X509_V_ERR_OCSP_VERIFY_NEEDED>
|
||||
|
||||
Returned by the verify callback to indicate an OCSP verification is needed.
|
||||
|
||||
=item B<X509_V_ERR_OCSP_VERIFY_FAILED>
|
||||
|
||||
Returned by the verify callback to indicate OCSP verification failed.
|
||||
|
||||
=item B<X509_V_ERR_OCSP_CERT_UNKNOWN>
|
||||
|
||||
Returned by the verify callback to indicate that the certificate is not recognized
|
||||
by the OCSP responder.
|
||||
|
||||
=back
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
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 the certificates in the file will be recognised.
|
||||
|
||||
Previous versions of OpenSSL 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<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<x509(1)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The B<-show_chain> option was added in OpenSSL 1.1.0.
|
||||
|
||||
The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
|
||||
is silently ignored.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,81 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-version,
|
||||
version - print OpenSSL version information
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl version>
|
||||
[B<-help>]
|
||||
[B<-a>]
|
||||
[B<-v>]
|
||||
[B<-b>]
|
||||
[B<-o>]
|
||||
[B<-f>]
|
||||
[B<-p>]
|
||||
[B<-d>]
|
||||
[B<-e>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This command is used to print out version information about OpenSSL.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-b>
|
||||
|
||||
The date the current version of OpenSSL was built.
|
||||
|
||||
=item B<-o>
|
||||
|
||||
Option information: various options set when the library was built.
|
||||
|
||||
=item B<-f>
|
||||
|
||||
Compilation flags.
|
||||
|
||||
=item B<-p>
|
||||
|
||||
Platform setting.
|
||||
|
||||
=item B<-d>
|
||||
|
||||
OPENSSLDIR setting.
|
||||
|
||||
=item B<-e>
|
||||
|
||||
ENGINESDIR setting.
|
||||
|
||||
=back
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The output of B<openssl version -a> would typically be used when sending
|
||||
in a bug report.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2017 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
|
||||
@@ -0,0 +1,942 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
openssl-x509,
|
||||
x509 - Certificate display and signing utility
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
B<openssl> B<x509>
|
||||
[B<-help>]
|
||||
[B<-inform DER|PEM>]
|
||||
[B<-outform DER|PEM>]
|
||||
[B<-keyform DER|PEM|ENGINE>]
|
||||
[B<-CAform DER|PEM>]
|
||||
[B<-CAkeyform DER|PEM>]
|
||||
[B<-in filename>]
|
||||
[B<-out filename>]
|
||||
[B<-serial>]
|
||||
[B<-hash>]
|
||||
[B<-subject_hash>]
|
||||
[B<-issuer_hash>]
|
||||
[B<-ocspid>]
|
||||
[B<-subject>]
|
||||
[B<-issuer>]
|
||||
[B<-nameopt option>]
|
||||
[B<-email>]
|
||||
[B<-ocsp_uri>]
|
||||
[B<-startdate>]
|
||||
[B<-enddate>]
|
||||
[B<-purpose>]
|
||||
[B<-dates>]
|
||||
[B<-checkend num>]
|
||||
[B<-modulus>]
|
||||
[B<-pubkey>]
|
||||
[B<-fingerprint>]
|
||||
[B<-alias>]
|
||||
[B<-noout>]
|
||||
[B<-trustout>]
|
||||
[B<-clrtrust>]
|
||||
[B<-clrreject>]
|
||||
[B<-addtrust arg>]
|
||||
[B<-addreject arg>]
|
||||
[B<-setalias arg>]
|
||||
[B<-days arg>]
|
||||
[B<-set_serial n>]
|
||||
[B<-signkey arg>]
|
||||
[B<-passin arg>]
|
||||
[B<-x509toreq>]
|
||||
[B<-req>]
|
||||
[B<-CA filename>]
|
||||
[B<-CAkey filename>]
|
||||
[B<-CAcreateserial>]
|
||||
[B<-CAserial filename>]
|
||||
[B<-force_pubkey key>]
|
||||
[B<-text>]
|
||||
[B<-ext extensions>]
|
||||
[B<-certopt option>]
|
||||
[B<-C>]
|
||||
[B<-I<digest>>]
|
||||
[B<-clrext>]
|
||||
[B<-extfile filename>]
|
||||
[B<-extensions section>]
|
||||
[B<-sigopt nm:v>]
|
||||
[B<-rand file...>]
|
||||
[B<-writerand file>]
|
||||
[B<-engine id>]
|
||||
[B<-preserve_dates>]
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<x509> command is a multi purpose certificate utility. It can be
|
||||
used to display certificate information, convert certificates to
|
||||
various forms, sign certificate requests like a "mini CA" or edit
|
||||
certificate trust settings.
|
||||
|
||||
Since there are a large number of options they will split up into
|
||||
various sections.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=head2 Input, Output, and General Purpose Options
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-help>
|
||||
|
||||
Print out a usage message.
|
||||
|
||||
=item B<-inform DER|PEM>
|
||||
|
||||
This specifies the input format normally the command will expect an X509
|
||||
certificate but this can change if other options such as B<-req> are
|
||||
present. The DER format is the DER encoding of the certificate and PEM
|
||||
is the base64 encoding of the DER encoding with header and footer lines
|
||||
added. The default format is PEM.
|
||||
|
||||
=item B<-outform DER|PEM>
|
||||
|
||||
This specifies the output format, the options have the same meaning and default
|
||||
as the B<-inform> option.
|
||||
|
||||
=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<-I<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 OpenSSL 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.
|
||||
|
||||
=item B<-rand file...>
|
||||
|
||||
A file or files containing random data used to seed the random number
|
||||
generator.
|
||||
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<-writerand file>]
|
||||
|
||||
Writes random data to the specified I<file> upon exit.
|
||||
This can be used with a subsequent B<-rand> flag.
|
||||
|
||||
=item B<-engine id>
|
||||
|
||||
Specifying an engine (by its unique B<id> string) will cause B<x509>
|
||||
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<-preserve_dates>
|
||||
|
||||
When signing a certificate, preserve the "notBefore" and "notAfter" dates instead
|
||||
of adjusting them to current time and duration. Cannot be used with the B<-days> option.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Display Options
|
||||
|
||||
Note: the B<-alias> and B<-purpose> options are also display options
|
||||
but are described in the B<TRUST SETTINGS> section.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-text>
|
||||
|
||||
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<-ext extensions>
|
||||
|
||||
Prints out the certificate extensions in text form. Extensions are specified
|
||||
with a comma separated string, e.g., "subjectAltName,subjectKeyIdentifier".
|
||||
See the L<x509v3_config(5)> manual page for the extension names.
|
||||
|
||||
=item B<-certopt option>
|
||||
|
||||
Customise the output format used with B<-text>. The B<option> argument
|
||||
can be 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.
|
||||
|
||||
=item B<-noout>
|
||||
|
||||
This option prevents output of the encoded version of the certificate.
|
||||
|
||||
=item B<-pubkey>
|
||||
|
||||
Outputs the certificate's SubjectPublicKeyInfo block in PEM format.
|
||||
|
||||
=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
|
||||
form an index to allow certificates in a directory to be looked up by subject
|
||||
name.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-hash>
|
||||
|
||||
Synonym for "-subject_hash" for backward compatibility reasons.
|
||||
|
||||
=item B<-subject_hash_old>
|
||||
|
||||
Outputs the "hash" of the certificate subject name using the older algorithm
|
||||
as used by OpenSSL before version 1.0.0.
|
||||
|
||||
=item B<-issuer_hash_old>
|
||||
|
||||
Outputs the "hash" of the certificate issuer name using the older algorithm
|
||||
as used by OpenSSL before version 1.0.0.
|
||||
|
||||
=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
|
||||
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.
|
||||
|
||||
=item B<-email>
|
||||
|
||||
Outputs the email address(es) if any.
|
||||
|
||||
=item B<-ocsp_uri>
|
||||
|
||||
Outputs the OCSP responder address(es) if any.
|
||||
|
||||
=item B<-startdate>
|
||||
|
||||
Prints out the start date of the certificate, that is the notBefore date.
|
||||
|
||||
=item B<-enddate>
|
||||
|
||||
Prints out the expiry date of the certificate, that is the notAfter date.
|
||||
|
||||
=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
|
||||
nonzero if yes it will expire or zero if not.
|
||||
|
||||
=item B<-fingerprint>
|
||||
|
||||
Calculates and outputs the digest of the DER encoded version of the entire
|
||||
certificate (see digest options).
|
||||
This is commonly called a "fingerprint". Because of the nature of message
|
||||
digests, the fingerprint of a certificate is unique to that certificate and
|
||||
two certificates with the same fingerprint can be considered to be the same.
|
||||
|
||||
=item B<-C>
|
||||
|
||||
This outputs the certificate in the form of a C source file.
|
||||
|
||||
=back
|
||||
|
||||
=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
|
||||
and prohibited uses of the certificate and an "alias".
|
||||
|
||||
Normally when a certificate is being verified at least one certificate
|
||||
must be "trusted". By default a trusted certificate must be stored
|
||||
locally and must be a root CA: any certificate chain ending in this CA
|
||||
is then usable for any purpose.
|
||||
|
||||
Trust settings currently are only used with a root CA. They allow a finer
|
||||
control over the purposes the root CA can be used for. For example a CA
|
||||
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
|
||||
certificate: not just root CAs.
|
||||
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-trustout>
|
||||
|
||||
This causes B<x509> to output a B<trusted> certificate. An ordinary
|
||||
or trusted certificate can be input but by default an ordinary
|
||||
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.
|
||||
|
||||
=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".
|
||||
|
||||
=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), B<emailProtection> (S/MIME email) and
|
||||
B<anyExtendedKeyUsage> are used.
|
||||
As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
|
||||
enables all purposes when trusted.
|
||||
Other OpenSSL applications may define additional uses.
|
||||
|
||||
=item B<-addreject arg>
|
||||
|
||||
Adds a prohibited use. It accepts the same values as the B<-addtrust>
|
||||
option.
|
||||
|
||||
=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.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Signing Options
|
||||
|
||||
The B<x509> utility can be used to sign certificates and requests: it
|
||||
can thus behave like a "mini CA".
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<-signkey arg>
|
||||
|
||||
This option causes the input file to be self signed using the supplied
|
||||
private key or engine. The private key's format is specified with the
|
||||
B<-keyform> option.
|
||||
|
||||
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; 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.
|
||||
|
||||
=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 key password source. For more information about the format of B<arg>
|
||||
see L<openssl(1)/Pass Phrase Options>.
|
||||
|
||||
=item B<-clrext>
|
||||
|
||||
Delete any extensions from a certificate. This option is used when a
|
||||
certificate is being created from another certificate (for example with
|
||||
the B<-signkey> or the B<-CA> options). Normally all extensions are
|
||||
retained.
|
||||
|
||||
=item B<-keyform PEM|DER|ENGINE>
|
||||
|
||||
Specifies the format (DER or PEM) of the private key file used in the
|
||||
B<-signkey> option.
|
||||
|
||||
=item B<-days arg>
|
||||
|
||||
Specifies the number of days to make a certificate valid for. The default
|
||||
is 30 days. Cannot be used with the B<-preserve_dates> option.
|
||||
|
||||
=item B<-x509toreq>
|
||||
|
||||
Converts a certificate into a certificate request. The B<-signkey> option
|
||||
is used to pass the required private key.
|
||||
|
||||
=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
|
||||
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>).
|
||||
|
||||
=item B<-CA filename>
|
||||
|
||||
Specifies the CA certificate to be used for signing. When this option is
|
||||
present B<x509> behaves like a "mini CA". The input file is signed by this
|
||||
CA using this option: that is its issuer name is set to the subject name
|
||||
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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<-CAserial filename>
|
||||
|
||||
Sets the CA serial number file to use.
|
||||
|
||||
When the B<-CA> option is used to sign a certificate it uses a serial
|
||||
number specified in a file. This file consists of one line containing
|
||||
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
|
||||
"mycacert.pem" it expects to find a serial number file called "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. 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.
|
||||
|
||||
=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)> manual page for details of the
|
||||
extension section format.
|
||||
|
||||
=item B<-force_pubkey key>
|
||||
|
||||
When a certificate is created set its public key to B<key> instead of the
|
||||
key in the certificate or certificate request. This option is useful for
|
||||
creating certificates where the algorithm can't normally sign requests, for
|
||||
example DH.
|
||||
|
||||
The format or B<key> can be specified using the B<-keyform> option.
|
||||
|
||||
=back
|
||||
|
||||
=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.
|
||||
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.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<compat>
|
||||
|
||||
Use the old format.
|
||||
|
||||
=item B<RFC2253>
|
||||
|
||||
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>.
|
||||
|
||||
=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. This is the I<default> of no name options are given explicitly.
|
||||
|
||||
=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>.
|
||||
|
||||
=item B<esc_2253>
|
||||
|
||||
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.
|
||||
|
||||
=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<()*>.
|
||||
|
||||
=item B<esc_ctrl>
|
||||
|
||||
Escape control characters. That is those with ASCII values less than
|
||||
0x20 (space) and the delete (0x7f) character. They are escaped using the
|
||||
RFC2253 \XX notation (where XX are two hex digits representing the
|
||||
character value).
|
||||
|
||||
=item B<esc_msb>
|
||||
|
||||
Escape characters with the MSB set, that is with ASCII values larger than
|
||||
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
|
||||
you are lucky enough to have a UTF8 compatible terminal then the use
|
||||
of this option (and B<not> setting B<esc_msb>) may result in the correct
|
||||
display of multibyte (international) characters. Is this option is not
|
||||
present then multibyte characters larger than 0xff will be represented
|
||||
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.
|
||||
|
||||
=item B<ignore_type>
|
||||
|
||||
This option does not attempt to interpret multibyte characters in any
|
||||
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".
|
||||
|
||||
=item B<dump_der>
|
||||
|
||||
When this option is set any fields that need to be hexdumped will
|
||||
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.
|
||||
|
||||
=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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<dump_unknown>
|
||||
|
||||
Dump any field whose OID is not recognised by OpenSSL.
|
||||
|
||||
=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
|
||||
B<sep_multiline>
|
||||
|
||||
These options determine the field separators. The first character is
|
||||
between RDNs and the second between multiple AVAs (multiple AVAs are
|
||||
very rare and their use is discouraged). The options ending in
|
||||
"space" additionally place a space after the separator to make it
|
||||
more readable. The B<sep_multiline> uses a linefeed character for
|
||||
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.
|
||||
|
||||
=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.
|
||||
|
||||
=item B<nofname>, B<sname>, B<lname>, B<oid>
|
||||
|
||||
These options alter how the field name is displayed. B<nofname> does
|
||||
not display the field at all. B<sname> uses the "short name" form
|
||||
(CN for commonName for example). B<lname> uses the long form.
|
||||
B<oid> represents the OID in numerical form and is useful for
|
||||
diagnostic purpose.
|
||||
|
||||
=item B<align>
|
||||
|
||||
Align field values for a more readable output. Only usable with
|
||||
B<sep_multiline>.
|
||||
|
||||
=item B<space_eq>
|
||||
|
||||
Places spaces round the B<=> character which follows the field
|
||||
name.
|
||||
|
||||
=back
|
||||
|
||||
=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
|
||||
the B<text> option is present. The default behaviour is to print all fields.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<compatible>
|
||||
|
||||
Use the old format. This is equivalent to specifying no output options at all.
|
||||
|
||||
=item B<no_header>
|
||||
|
||||
Don't print header information: that is the lines saying "Certificate"
|
||||
and "Data".
|
||||
|
||||
=item B<no_version>
|
||||
|
||||
Don't print out the version number.
|
||||
|
||||
=item B<no_serial>
|
||||
|
||||
Don't print out the serial number.
|
||||
|
||||
=item B<no_signame>
|
||||
|
||||
Don't print out the signature algorithm used.
|
||||
|
||||
=item B<no_validity>
|
||||
|
||||
Don't print the validity, that is the B<notBefore> and B<notAfter> fields.
|
||||
|
||||
=item B<no_subject>
|
||||
|
||||
Don't print out the subject name.
|
||||
|
||||
=item B<no_issuer>
|
||||
|
||||
Don't print out the issuer name.
|
||||
|
||||
=item B<no_pubkey>
|
||||
|
||||
Don't print out the public key.
|
||||
|
||||
=item B<no_sigdump>
|
||||
|
||||
Don't give a hexadecimal dump of the certificate signature.
|
||||
|
||||
=item B<no_aux>
|
||||
|
||||
Don't print out certificate trust information.
|
||||
|
||||
=item B<no_extensions>
|
||||
|
||||
Don't print out any X509V3 extensions.
|
||||
|
||||
=item B<ext_default>
|
||||
|
||||
Retain default extension behaviour: attempt to print out unsupported
|
||||
certificate extensions.
|
||||
|
||||
=item B<ext_error>
|
||||
|
||||
Print an error message for unsupported certificate extensions.
|
||||
|
||||
=item B<ext_parse>
|
||||
|
||||
ASN1 parse unsupported extensions.
|
||||
|
||||
=item B<ext_dump>
|
||||
|
||||
Hex dump unsupported extensions.
|
||||
|
||||
=item B<ca_default>
|
||||
|
||||
The value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>,
|
||||
B<no_header>, and B<no_version>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Note: in these examples the '\' means the example should be all on one
|
||||
line.
|
||||
|
||||
Display the contents of a certificate:
|
||||
|
||||
openssl x509 -in cert.pem -noout -text
|
||||
|
||||
Display the "Subject Alternative Name" extension of a certificate:
|
||||
|
||||
openssl x509 -in cert.pem -noout -ext subjectAltName
|
||||
|
||||
Display more extensions of a certificate:
|
||||
|
||||
openssl x509 -in cert.pem -noout -ext subjectAltName,nsCertType
|
||||
|
||||
Display the certificate serial number:
|
||||
|
||||
openssl x509 -in cert.pem -noout -serial
|
||||
|
||||
Display the certificate subject name:
|
||||
|
||||
openssl x509 -in cert.pem -noout -subject
|
||||
|
||||
Display the certificate subject name in RFC2253 form:
|
||||
|
||||
openssl 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
|
||||
|
||||
Display the certificate SHA1 fingerprint:
|
||||
|
||||
openssl 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
|
||||
|
||||
Convert a certificate to a certificate request:
|
||||
|
||||
openssl 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
|
||||
|
||||
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
|
||||
|
||||
|
||||
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
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The PEM format uses the header and footer lines:
|
||||
|
||||
-----BEGIN CERTIFICATE-----
|
||||
-----END CERTIFICATE-----
|
||||
|
||||
it will also handle files containing:
|
||||
|
||||
-----BEGIN X509 CERTIFICATE-----
|
||||
-----END X509 CERTIFICATE-----
|
||||
|
||||
Trusted certificates have the lines
|
||||
|
||||
-----BEGIN TRUSTED CERTIFICATE-----
|
||||
-----END TRUSTED CERTIFICATE-----
|
||||
|
||||
The conversion to UTF8 format used with the name options assumes that
|
||||
T61Strings use the ISO8859-1 character set. This is wrong but Netscape
|
||||
and MSIE do this as do many certificates. So although this is incorrect
|
||||
it is more likely to display the majority of certificates correctly.
|
||||
|
||||
The B<-email> option searches the subject name and the subject alternative
|
||||
name extension. Only unique email addresses will be printed out: it will
|
||||
not print the same address more than once.
|
||||
|
||||
=head1 CERTIFICATE EXTENSIONS
|
||||
|
||||
The B<-purpose> option checks the certificate extensions and determines
|
||||
what the certificate can be used for. The actual checks done are rather
|
||||
complex and include various hacks and workarounds to handle broken
|
||||
certificates and software.
|
||||
|
||||
The same code is used when verifying untrusted certificates in chains
|
||||
so this section is useful if a chain is rejected by the verify code.
|
||||
|
||||
The basicConstraints extension CA flag is used to determine whether the
|
||||
certificate can be used as a CA. If the CA flag is true then it is a CA,
|
||||
if the CA flag is false then it is not a CA. B<All> CAs should have the
|
||||
CA flag set to true.
|
||||
|
||||
If the basicConstraints extension is absent then the certificate is
|
||||
considered to be a "possible CA" other extensions are checked according
|
||||
to the intended use of the certificate. A warning is given in this case
|
||||
because the certificate should really not be regarded as a CA: however
|
||||
it is allowed to be a CA to work around some broken software.
|
||||
|
||||
If the certificate is a V1 certificate (and thus has no extensions) and
|
||||
it is self signed it is also assumed to be a CA but a warning is again
|
||||
given: this is to work around the problem of Verisign roots which are V1
|
||||
self signed certificates.
|
||||
|
||||
If the keyUsage extension is present then additional restraints are
|
||||
made on the uses of the certificate. A CA certificate B<must> have the
|
||||
keyCertSign bit set if the keyUsage extension is present.
|
||||
|
||||
The extended key usage extension places additional restrictions on the
|
||||
certificate uses. If this extension is present (whether critical or not)
|
||||
the key can only be used for the purposes specified.
|
||||
|
||||
A complete description of each test is given below. The comments about
|
||||
basicConstraints and keyUsage and V1 certificates above apply to B<all>
|
||||
CA certificates.
|
||||
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<SSL Client>
|
||||
|
||||
The extended key usage extension must be absent or include the "web client
|
||||
authentication" OID. keyUsage must be absent or it must have the
|
||||
digitalSignature bit set. Netscape certificate type must be absent or it must
|
||||
have the SSL client bit set.
|
||||
|
||||
=item B<SSL Client CA>
|
||||
|
||||
The extended key usage extension must be absent or include the "web client
|
||||
authentication" OID. Netscape certificate type must be absent or it must have
|
||||
the SSL CA bit set: this is used as a work around if the basicConstraints
|
||||
extension is absent.
|
||||
|
||||
=item B<SSL Server>
|
||||
|
||||
The extended key usage extension must be absent or include the "web server
|
||||
authentication" and/or one of the SGC OIDs. keyUsage must be absent or it
|
||||
must have the digitalSignature, the keyEncipherment set or both bits set.
|
||||
Netscape certificate type must be absent or have the SSL server bit set.
|
||||
|
||||
=item B<SSL Server CA>
|
||||
|
||||
The extended key usage extension must be absent or include the "web server
|
||||
authentication" and/or one of the SGC OIDs. Netscape certificate type must
|
||||
be absent or the SSL CA bit must be set: this is used as a work around if the
|
||||
basicConstraints extension is absent.
|
||||
|
||||
=item B<Netscape SSL Server>
|
||||
|
||||
For Netscape SSL clients to connect to an SSL server it must have the
|
||||
keyEncipherment bit set if the keyUsage extension is present. This isn't
|
||||
always valid because some cipher suites use the key for digital signing.
|
||||
Otherwise it is the same as a normal SSL server.
|
||||
|
||||
=item B<Common S/MIME Client Tests>
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
=item B<S/MIME Signing>
|
||||
|
||||
In addition to the common S/MIME client tests the digitalSignature bit or
|
||||
the nonRepudiation bit must be set if the keyUsage extension is present.
|
||||
|
||||
=item B<S/MIME Encryption>
|
||||
|
||||
In addition to the common S/MIME tests the keyEncipherment bit must be set
|
||||
if the keyUsage extension is present.
|
||||
|
||||
=item B<S/MIME CA>
|
||||
|
||||
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.
|
||||
|
||||
=item B<CRL Signing>
|
||||
|
||||
The keyUsage extension must be absent or it must have the CRL signing bit
|
||||
set.
|
||||
|
||||
=item B<CRL Signing CA>
|
||||
|
||||
The normal CA tests apply. Except in this case the basicConstraints extension
|
||||
must be present.
|
||||
|
||||
=back
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
Extensions in certificates are not transferred to certificate requests and
|
||||
vice versa.
|
||||
|
||||
It is possible to produce invalid certificates or requests by specifying the
|
||||
wrong private key or using inconsistent options in some cases: these should
|
||||
be checked.
|
||||
|
||||
There should be options to explicitly set such things as start and end
|
||||
dates rather than an offset from the current time.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<req(1)>, L<ca(1)>, L<genrsa(1)>,
|
||||
L<gendsa(1)>, L<verify(1)>,
|
||||
L<x509v3_config(5)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2021 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
|
||||
@@ -0,0 +1,179 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ADMISSIONS,
|
||||
ADMISSIONS_get0_admissionAuthority,
|
||||
ADMISSIONS_get0_namingAuthority,
|
||||
ADMISSIONS_get0_professionInfos,
|
||||
ADMISSIONS_set0_admissionAuthority,
|
||||
ADMISSIONS_set0_namingAuthority,
|
||||
ADMISSIONS_set0_professionInfos,
|
||||
ADMISSION_SYNTAX,
|
||||
ADMISSION_SYNTAX_get0_admissionAuthority,
|
||||
ADMISSION_SYNTAX_get0_contentsOfAdmissions,
|
||||
ADMISSION_SYNTAX_set0_admissionAuthority,
|
||||
ADMISSION_SYNTAX_set0_contentsOfAdmissions,
|
||||
NAMING_AUTHORITY,
|
||||
NAMING_AUTHORITY_get0_authorityId,
|
||||
NAMING_AUTHORITY_get0_authorityURL,
|
||||
NAMING_AUTHORITY_get0_authorityText,
|
||||
NAMING_AUTHORITY_set0_authorityId,
|
||||
NAMING_AUTHORITY_set0_authorityURL,
|
||||
NAMING_AUTHORITY_set0_authorityText,
|
||||
PROFESSION_INFO,
|
||||
PROFESSION_INFOS,
|
||||
PROFESSION_INFO_get0_addProfessionInfo,
|
||||
PROFESSION_INFO_get0_namingAuthority,
|
||||
PROFESSION_INFO_get0_professionItems,
|
||||
PROFESSION_INFO_get0_professionOIDs,
|
||||
PROFESSION_INFO_get0_registrationNumber,
|
||||
PROFESSION_INFO_set0_addProfessionInfo,
|
||||
PROFESSION_INFO_set0_namingAuthority,
|
||||
PROFESSION_INFO_set0_professionItems,
|
||||
PROFESSION_INFO_set0_professionOIDs,
|
||||
PROFESSION_INFO_set0_registrationNumber
|
||||
- Accessors and settors for ADMISSION_SYNTAX
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
typedef struct NamingAuthority_st NAMING_AUTHORITY;
|
||||
typedef struct ProfessionInfo_st PROFESSION_INFO;
|
||||
typedef STACK_OF(PROFESSION_INFO) PROFESSION_INFOS;
|
||||
typedef struct Admissions_st ADMISSIONS;
|
||||
typedef struct AdmissionSyntax_st ADMISSION_SYNTAX;
|
||||
|
||||
const ASN1_OBJECT *NAMING_AUTHORITY_get0_authorityId(
|
||||
const NAMING_AUTHORITY *n);
|
||||
void NAMING_AUTHORITY_set0_authorityId(NAMING_AUTHORITY *n,
|
||||
ASN1_OBJECT* namingAuthorityId);
|
||||
const ASN1_IA5STRING *NAMING_AUTHORITY_get0_authorityURL(
|
||||
const NAMING_AUTHORITY *n);
|
||||
void NAMING_AUTHORITY_set0_authorityURL(NAMING_AUTHORITY *n,
|
||||
ASN1_IA5STRING* namingAuthorityUrl);
|
||||
const ASN1_STRING *NAMING_AUTHORITY_get0_authorityText(
|
||||
const NAMING_AUTHORITY *n);
|
||||
void NAMING_AUTHORITY_set0_authorityText(NAMING_AUTHORITY *n,
|
||||
ASN1_STRING* namingAuthorityText);
|
||||
|
||||
const GENERAL_NAME *ADMISSION_SYNTAX_get0_admissionAuthority(
|
||||
const ADMISSION_SYNTAX *as);
|
||||
void ADMISSION_SYNTAX_set0_admissionAuthority(
|
||||
ADMISSION_SYNTAX *as, GENERAL_NAME *aa);
|
||||
const STACK_OF(ADMISSIONS) *ADMISSION_SYNTAX_get0_contentsOfAdmissions(
|
||||
const ADMISSION_SYNTAX *as);
|
||||
void ADMISSION_SYNTAX_set0_contentsOfAdmissions(
|
||||
ADMISSION_SYNTAX *as, STACK_OF(ADMISSIONS) *a);
|
||||
|
||||
const GENERAL_NAME *ADMISSIONS_get0_admissionAuthority(const ADMISSIONS *a);
|
||||
void ADMISSIONS_set0_admissionAuthority(ADMISSIONS *a, GENERAL_NAME *aa);
|
||||
const NAMING_AUTHORITY *ADMISSIONS_get0_namingAuthority(const ADMISSIONS *a);
|
||||
void ADMISSIONS_set0_namingAuthority(ADMISSIONS *a, NAMING_AUTHORITY *na);
|
||||
const PROFESSION_INFOS *ADMISSIONS_get0_professionInfos(const ADMISSIONS *a);
|
||||
void ADMISSIONS_set0_professionInfos(ADMISSIONS *a, PROFESSION_INFOS *pi);
|
||||
|
||||
const ASN1_OCTET_STRING *PROFESSION_INFO_get0_addProfessionInfo(
|
||||
const PROFESSION_INFO *pi);
|
||||
void PROFESSION_INFO_set0_addProfessionInfo(
|
||||
PROFESSION_INFO *pi, ASN1_OCTET_STRING *aos);
|
||||
const NAMING_AUTHORITY *PROFESSION_INFO_get0_namingAuthority(
|
||||
const PROFESSION_INFO *pi);
|
||||
void PROFESSION_INFO_set0_namingAuthority(
|
||||
PROFESSION_INFO *pi, NAMING_AUTHORITY *na);
|
||||
const STACK_OF(ASN1_STRING) *PROFESSION_INFO_get0_professionItems(
|
||||
const PROFESSION_INFO *pi);
|
||||
void PROFESSION_INFO_set0_professionItems(
|
||||
PROFESSION_INFO *pi, STACK_OF(ASN1_STRING) *as);
|
||||
const STACK_OF(ASN1_OBJECT) *PROFESSION_INFO_get0_professionOIDs(
|
||||
const PROFESSION_INFO *pi);
|
||||
void PROFESSION_INFO_set0_professionOIDs(
|
||||
PROFESSION_INFO *pi, STACK_OF(ASN1_OBJECT) *po);
|
||||
const ASN1_PRINTABLESTRING *PROFESSION_INFO_get0_registrationNumber(
|
||||
const PROFESSION_INFO *pi);
|
||||
void PROFESSION_INFO_set0_registrationNumber(
|
||||
PROFESSION_INFO *pi, ASN1_PRINTABLESTRING *rn);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<PROFESSION_INFOS>, B<ADMISSION_SYNTAX>, B<ADMISSIONS>, and
|
||||
B<PROFESSION_INFO> types are opaque structures representing the
|
||||
analogous types defined in the Common PKI Specification published
|
||||
by L<https://www.t7ev.org>.
|
||||
Knowledge of those structures and their semantics is assumed.
|
||||
|
||||
The conventional routines to convert between DER and the local format
|
||||
are described in L<d2i_X509(3)>.
|
||||
The conventional routines to allocate and free the types are defined
|
||||
in L<X509_dup(3)>.
|
||||
|
||||
The B<PROFESSION_INFOS> type is a stack of B<PROFESSION_INFO>; see
|
||||
L<DEFINE_STACK_OF(3)> for details.
|
||||
|
||||
The B<NAMING_AUTHORITY> type has an authority ID and URL, and text fields.
|
||||
The NAMING_AUTHORITY_get0_authorityId(),
|
||||
NAMING_AUTHORITY_get0_get0_authorityURL(), and
|
||||
NAMING_AUTHORITY_get0_get0_authorityText(), functions return pointers
|
||||
to those values within the object.
|
||||
The NAMING_AUTHORITY_set0_authorityId(),
|
||||
NAMING_AUTHORITY_set0_get0_authorityURL(), and
|
||||
NAMING_AUTHORITY_set0_get0_authorityText(),
|
||||
functions free any existing value and set the pointer to the specified value.
|
||||
|
||||
The B<ADMISSION_SYNTAX> type has an authority name and a stack of
|
||||
B<ADMISSION> objects.
|
||||
The ADMISSION_SYNTAX_get0_admissionAuthority()
|
||||
and ADMISSION_SYNTAX_get0_contentsOfAdmissions() functions return pointers
|
||||
to those values within the object.
|
||||
The
|
||||
ADMISSION_SYNTAX_set0_admissionAuthority() and
|
||||
ADMISSION_SYNTAX_set0_contentsOfAdmissions()
|
||||
functions free any existing value and set the pointer to the specified value.
|
||||
|
||||
The B<ADMISSION> type has an authority name, authority object, and a
|
||||
stack of B<PROFESSION_INFO> items.
|
||||
The ADMISSIONS_get0_admissionAuthority(), ADMISSIONS_get0_namingAuthority(),
|
||||
and ADMISSIONS_get0_professionInfos()
|
||||
functions return pointers to those values within the object.
|
||||
The
|
||||
ADMISSIONS_set0_admissionAuthority(),
|
||||
ADMISSIONS_set0_namingAuthority(), and
|
||||
ADMISSIONS_set0_professionInfos()
|
||||
functions free any existing value and set the pointer to the specified value.
|
||||
|
||||
The B<PROFESSION_INFO> type has a name authority, stacks of
|
||||
profession Items and OIDs, a registration number, and additional
|
||||
profession info.
|
||||
The functions PROFESSION_INFO_get0_addProfessionInfo(),
|
||||
PROFESSION_INFO_get0_namingAuthority(), PROFESSION_INFO_get0_professionItems(),
|
||||
PROFESSION_INFO_get0_professionOIDs(), and
|
||||
PROFESSION_INFO_get0_registrationNumber()
|
||||
functions return pointers to those values within the object.
|
||||
The
|
||||
PROFESSION_INFO_set0_addProfessionInfo(),
|
||||
PROFESSION_INFO_set0_namingAuthority(),
|
||||
PROFESSION_INFO_set0_professionItems(),
|
||||
PROFESSION_INFO_set0_professionOIDs(), and
|
||||
PROFESSION_INFO_set0_registrationNumber()
|
||||
functions free any existing value and set the pointer to the specified value.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
Described above.
|
||||
Note that all of the I<get0> functions return a pointer to the internal data
|
||||
structure and must not be freed.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<X509_dup(3)>,
|
||||
L<d2i_X509(3)>,
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017-2019 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
|
||||
@@ -0,0 +1,133 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64,
|
||||
ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN
|
||||
- ASN.1 INTEGER and ENUMERATED utilities
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
|
||||
long ASN1_INTEGER_get(const ASN1_INTEGER *a);
|
||||
|
||||
int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
|
||||
int ASN1_INTEGER_set(const ASN1_INTEGER *a, long v);
|
||||
|
||||
int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);
|
||||
int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);
|
||||
|
||||
ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
|
||||
BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
|
||||
|
||||
int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_ENUMERATED *a);
|
||||
long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
|
||||
|
||||
int ASN1_ENUMERATED_set_int64(ASN1_ENUMERATED *a, int64_t r);
|
||||
int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
|
||||
|
||||
ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
|
||||
BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED>
|
||||
structures.
|
||||
|
||||
ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type
|
||||
If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails
|
||||
(due to invalid type or the value being too big to fit into an B<int64_t> type)
|
||||
it returns 0.
|
||||
|
||||
ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it
|
||||
converts to a B<uint64_t> type and an error is returned if the passed integer
|
||||
is negative.
|
||||
|
||||
ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is
|
||||
NULL and -1 on error (which is ambiguous because -1 is a legitimate value for
|
||||
an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64()
|
||||
instead.
|
||||
|
||||
ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the
|
||||
B<int64_t> value B<r>.
|
||||
|
||||
ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the
|
||||
B<uint64_t> value B<r>.
|
||||
|
||||
ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
|
||||
B<v>.
|
||||
|
||||
BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai>
|
||||
is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then
|
||||
the existing structure will be used instead.
|
||||
|
||||
ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is
|
||||
NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the
|
||||
existing structure will be used instead.
|
||||
|
||||
ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
|
||||
ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN()
|
||||
behave in an identical way to their ASN1_INTEGER counterparts except they
|
||||
operate on an B<ASN1_ENUMERATED> value.
|
||||
|
||||
ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to
|
||||
ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not
|
||||
fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
|
||||
instead.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an
|
||||
integer of almost arbitrary size and so cannot always be represented by a C
|
||||
B<int64_t> type. However, in many cases (for example version numbers) they
|
||||
represent small integers which can be more easily manipulated if converted to
|
||||
an appropriate C integer type.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get()
|
||||
mean these functions should be avoided if possible. They are retained for
|
||||
compatibility. Normally the ambiguous return values are not legitimate
|
||||
values for the fields they represent.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and
|
||||
ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only
|
||||
fail if a memory allocation error occurs.
|
||||
|
||||
ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success
|
||||
and 0 for failure. They will fail if the passed type is incorrect (this will
|
||||
only happen if there is a programming error) or if the value exceeds the range
|
||||
of an B<int64_t> type.
|
||||
|
||||
BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or
|
||||
B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will
|
||||
only fail due to a memory allocation error.
|
||||
|
||||
ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure
|
||||
of NULL if an error occurs. They can fail if the passed type is incorrect
|
||||
(due to programming error) or due to a memory allocation failure.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(),
|
||||
ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64()
|
||||
were added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2015-2020 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
|
||||
@@ -0,0 +1,39 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_ITEM_lookup, ASN1_ITEM_get - lookup ASN.1 structures
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
const ASN1_ITEM *ASN1_ITEM_lookup(const char *name);
|
||||
const ASN1_ITEM *ASN1_ITEM_get(size_t i);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
ASN1_ITEM_lookup() returns the B<ASN1_ITEM name>.
|
||||
|
||||
ASN1_ITEM_get() returns the B<ASN1_ITEM> with index B<i>. This function
|
||||
returns B<NULL> if the index B<i> is out of range.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_ITEM_lookup() and ASN1_ITEM_get() return a valid B<ASN1_ITEM> structure
|
||||
or B<NULL> if an error occurred.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 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
|
||||
@@ -0,0 +1,51 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
ASN1_OBJECT *ASN1_OBJECT_new(void);
|
||||
void ASN1_OBJECT_free(ASN1_OBJECT *a);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The ASN1_OBJECT allocation routines, allocate and free an
|
||||
ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
|
||||
|
||||
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
|
||||
|
||||
Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
|
||||
is almost never used in applications. The ASN1 object utility functions
|
||||
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)>.
|
||||
Otherwise it returns a pointer to the newly allocated structure.
|
||||
|
||||
ASN1_OBJECT_free() returns no value.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)>
|
||||
|
||||
=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
|
||||
@@ -0,0 +1,65 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_STRING_TABLE, ASN1_STRING_TABLE_add, ASN1_STRING_TABLE_get,
|
||||
ASN1_STRING_TABLE_cleanup - ASN1_STRING_TABLE manipulation functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
typedef struct asn1_string_table_st ASN1_STRING_TABLE;
|
||||
|
||||
int ASN1_STRING_TABLE_add(int nid, long minsize, long maxsize,
|
||||
unsigned long mask, unsigned long flags);
|
||||
ASN1_STRING_TABLE * ASN1_STRING_TABLE_get(int nid);
|
||||
void ASN1_STRING_TABLE_cleanup(void);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
=head2 Types
|
||||
|
||||
B<ASN1_STRING_TABLE> is a table which holds string information
|
||||
(basically minimum size, maximum size, type and etc) for a NID object.
|
||||
|
||||
=head2 Functions
|
||||
|
||||
ASN1_STRING_TABLE_add() adds a new B<ASN1_STRING_TABLE> item into the
|
||||
local ASN1 string table based on the B<nid> along with other parameters.
|
||||
|
||||
If the item is already in the table, fields of B<ASN1_STRING_TABLE> are
|
||||
updated (depending on the values of those parameters, e.g., B<minsize>
|
||||
and B<maxsize> >= 0, B<mask> and B<flags> != 0). If the B<nid> is standard,
|
||||
a copy of the standard B<ASN1_STRING_TABLE> is created and updated with
|
||||
other parameters.
|
||||
|
||||
ASN1_STRING_TABLE_get() searches for an B<ASN1_STRING_TABLE> item based
|
||||
on B<nid>. It will search the local table first, then the standard one.
|
||||
|
||||
ASN1_STRING_TABLE_cleanup() frees all B<ASN1_STRING_TABLE> items added
|
||||
by ASN1_STRING_TABLE_add().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_STRING_TABLE_add() returns 1 on success, 0 if an error occurred.
|
||||
|
||||
ASN1_STRING_TABLE_get() returns a valid B<ASN1_STRING_TABLE> structure
|
||||
or B<NULL> if nothing is found.
|
||||
|
||||
ASN1_STRING_TABLE_cleanup() does not return a value.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 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
|
||||
@@ -0,0 +1,113 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
|
||||
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);
|
||||
|
||||
int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
|
||||
|
||||
int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
|
||||
|
||||
int ASN1_STRING_type(const ASN1_STRING *x);
|
||||
|
||||
int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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_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
|
||||
are identical. The string types and content are compared.
|
||||
|
||||
ASN1_STRING_set() sets the data of string B<str> to the buffer
|
||||
B<data> or length B<len>. The supplied data is copied. If B<len>
|
||||
is -1 then the length is determined by strlen(data).
|
||||
|
||||
ASN1_STRING_type() returns the type of B<x>, using standard constants
|
||||
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 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 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
|
||||
B<Time>.
|
||||
|
||||
These functions should B<not> be used to examine or modify B<ASN1_INTEGER>
|
||||
or B<ASN1_ENUMERATED> types: the relevant B<INTEGER> or B<ENUMERATED>
|
||||
utility functions should be used instead.
|
||||
|
||||
In general it cannot be assumed that the data returned by ASN1_STRING_data()
|
||||
is null terminated or does not contain embedded nulls. The actual format
|
||||
of the data will depend on the actual string type itself: for example
|
||||
for an IA5String the data will be ASCII, for a BMPString two bytes per
|
||||
character in big endian format, and for a UTF8String it 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
|
||||
|
||||
ASN1_STRING_length() returns the length of the content of B<x>.
|
||||
|
||||
ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to
|
||||
the data of B<x>.
|
||||
|
||||
ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or B<NULL> if an
|
||||
error occurred.
|
||||
|
||||
ASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0,
|
||||
according to whether B<a> is greater than, equal to, or less than B<b>.
|
||||
|
||||
ASN1_STRING_set() returns 1 on success or 0 on error.
|
||||
|
||||
ASN1_STRING_type() returns the type of B<x>.
|
||||
|
||||
ASN1_STRING_to_UTF8() returns the number of bytes in output string B<out> or a
|
||||
negative value if an error occurred.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2002-2020 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
|
||||
@@ -0,0 +1,52 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_STRING_new, ASN1_STRING_type_new, ASN1_STRING_free -
|
||||
ASN1_STRING allocation functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
ASN1_STRING * ASN1_STRING_new(void);
|
||||
ASN1_STRING * ASN1_STRING_type_new(int type);
|
||||
void ASN1_STRING_free(ASN1_STRING *a);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
ASN1_STRING_new() returns an allocated B<ASN1_STRING> structure. Its type
|
||||
is undefined.
|
||||
|
||||
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
|
||||
|
||||
Other string types call the B<ASN1_STRING> functions. For example
|
||||
ASN1_OCTET_STRING_new() calls ASN1_STRING_type(V_ASN1_OCTET_STRING).
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_STRING_new() and ASN1_STRING_type_new() return a valid
|
||||
ASN1_STRING structure or B<NULL> if an error occurred.
|
||||
|
||||
ASN1_STRING_free() does not return a value.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>
|
||||
|
||||
=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
|
||||
@@ -0,0 +1,115 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_tag2str, 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, 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);
|
||||
|
||||
const char *ASN1_tag2str(int tag);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
These functions output an B<ASN1_STRING> structure. B<ASN1_STRING> is used to
|
||||
represent all the ASN1 string types.
|
||||
|
||||
ASN1_STRING_print_ex() outputs B<str> to B<out>, the format is determined by
|
||||
the options B<flags>. ASN1_STRING_print_ex_fp() is identical except it outputs
|
||||
to B<fp> instead.
|
||||
|
||||
ASN1_STRING_print() prints B<str> to B<out> but using a different format to
|
||||
ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
|
||||
with '.'.
|
||||
|
||||
ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
ASN1_STRING_print() is a deprecated function which should be avoided; use
|
||||
ASN1_STRING_print_ex() instead.
|
||||
|
||||
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.
|
||||
|
||||
Various characters can be escaped. If B<ASN1_STRFLGS_ESC_2253> is set the characters
|
||||
determined by RFC2253 are escaped. If B<ASN1_STRFLGS_ESC_CTRL> is set control
|
||||
characters are escaped. If B<ASN1_STRFLGS_ESC_MSB> is set characters with the
|
||||
MSB set are escaped: this option should B<not> be used if the terminal correctly
|
||||
interprets UTF8 sequences.
|
||||
|
||||
Escaping takes several forms.
|
||||
|
||||
If the character being escaped is a 16 bit character then the form "\UXXXX" is used
|
||||
using exactly four characters for the hex representation. If it is 32 bits then
|
||||
"\WXXXXXXXX" is used using eight characters of its hex representation. These forms
|
||||
will only be used if UTF8 conversion is not set (see below).
|
||||
|
||||
Printable characters are normally escaped using the backslash '\' character. If
|
||||
B<ASN1_STRFLGS_ESC_QUOTE> is set then the whole string is instead surrounded by
|
||||
double quote characters: this is arguably more readable than the backslash
|
||||
notation. Other characters use the "\XX" using exactly two characters of the hex
|
||||
representation.
|
||||
|
||||
If B<ASN1_STRFLGS_UTF8_CONVERT> is set then characters are converted to UTF8
|
||||
format first. If the terminal supports the display of UTF8 sequences then this
|
||||
option will correctly display multi byte characters.
|
||||
|
||||
If B<ASN1_STRFLGS_IGNORE_TYPE> is set then the string type is not interpreted at
|
||||
all: everything is assumed to be one byte per character. This is primarily for
|
||||
debugging purposes and can result in confusing output in multi character strings.
|
||||
|
||||
If B<ASN1_STRFLGS_SHOW_TYPE> is set then the string type itself is printed out
|
||||
before its value (for example "BMPSTRING"), this actually uses ASN1_tag2str().
|
||||
|
||||
The content of a string instead of being interpreted can be "dumped": this just
|
||||
outputs the value of the string using the form #XXXX using hex format for each
|
||||
octet.
|
||||
|
||||
If B<ASN1_STRFLGS_DUMP_ALL> is set then any type is dumped.
|
||||
|
||||
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
|
||||
B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
|
||||
instead (including tag and length octets).
|
||||
|
||||
B<ASN1_STRFLGS_RFC2253> includes all the flags required by RFC2253. It is
|
||||
equivalent to:
|
||||
ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
|
||||
ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_STRING_print_ex() and ASN1_STRING_print_ex_fp() return the number of
|
||||
characters written or -1 if an error occurred.
|
||||
|
||||
ASN1_STRING_print() returns 1 on success or 0 on error.
|
||||
|
||||
ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<X509_NAME_print_ex(3)>,
|
||||
L<ASN1_tag2str(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2002-2018 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
|
||||
@@ -0,0 +1,258 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_TIME_set, ASN1_UTCTIME_set, ASN1_GENERALIZEDTIME_set,
|
||||
ASN1_TIME_adj, ASN1_UTCTIME_adj, ASN1_GENERALIZEDTIME_adj,
|
||||
ASN1_TIME_check, ASN1_UTCTIME_check, ASN1_GENERALIZEDTIME_check,
|
||||
ASN1_TIME_set_string, ASN1_UTCTIME_set_string, ASN1_GENERALIZEDTIME_set_string,
|
||||
ASN1_TIME_set_string_X509,
|
||||
ASN1_TIME_normalize,
|
||||
ASN1_TIME_to_tm,
|
||||
ASN1_TIME_print, ASN1_UTCTIME_print, ASN1_GENERALIZEDTIME_print,
|
||||
ASN1_TIME_diff,
|
||||
ASN1_TIME_cmp_time_t, ASN1_UTCTIME_cmp_time_t,
|
||||
ASN1_TIME_compare,
|
||||
ASN1_TIME_to_generalizedtime - ASN.1 Time functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
|
||||
ASN1_UTCTIME *ASN1_UTCTIME_set(ASN1_UTCTIME *s, time_t t);
|
||||
ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_set(ASN1_GENERALIZEDTIME *s,
|
||||
time_t t);
|
||||
|
||||
ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t, int offset_day,
|
||||
long offset_sec);
|
||||
ASN1_UTCTIME *ASN1_UTCTIME_adj(ASN1_UTCTIME *s, time_t t,
|
||||
int offset_day, long offset_sec);
|
||||
ASN1_GENERALIZEDTIME *ASN1_GENERALIZEDTIME_adj(ASN1_GENERALIZEDTIME *s,
|
||||
time_t t, int offset_day,
|
||||
long offset_sec);
|
||||
|
||||
int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
|
||||
int ASN1_TIME_set_string_X509(ASN1_TIME *s, const char *str);
|
||||
int ASN1_UTCTIME_set_string(ASN1_UTCTIME *s, const char *str);
|
||||
int ASN1_GENERALIZEDTIME_set_string(ASN1_GENERALIZEDTIME *s,
|
||||
const char *str);
|
||||
|
||||
int ASN1_TIME_normalize(ASN1_TIME *s);
|
||||
|
||||
int ASN1_TIME_check(const ASN1_TIME *t);
|
||||
int ASN1_UTCTIME_check(const ASN1_UTCTIME *t);
|
||||
int ASN1_GENERALIZEDTIME_check(const ASN1_GENERALIZEDTIME *t);
|
||||
|
||||
int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
|
||||
int ASN1_UTCTIME_print(BIO *b, const ASN1_UTCTIME *s);
|
||||
int ASN1_GENERALIZEDTIME_print(BIO *b, const ASN1_GENERALIZEDTIME *s);
|
||||
|
||||
int ASN1_TIME_to_tm(const ASN1_TIME *s, struct tm *tm);
|
||||
int ASN1_TIME_diff(int *pday, int *psec, const ASN1_TIME *from,
|
||||
const ASN1_TIME *to);
|
||||
|
||||
int ASN1_TIME_cmp_time_t(const ASN1_TIME *s, time_t t);
|
||||
int ASN1_UTCTIME_cmp_time_t(const ASN1_UTCTIME *s, time_t t);
|
||||
|
||||
int ASN1_TIME_compare(const ASN1_TIME *a, const ASN1_TIME *b);
|
||||
|
||||
ASN1_GENERALIZEDTIME *ASN1_TIME_to_generalizedtime(ASN1_TIME *t,
|
||||
ASN1_GENERALIZEDTIME **out);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The ASN1_TIME_set(), ASN1_UTCTIME_set() and ASN1_GENERALIZEDTIME_set()
|
||||
functions set the structure B<s> to the time represented by the time_t
|
||||
value B<t>. If B<s> is NULL a new time structure is allocated and returned.
|
||||
|
||||
The ASN1_TIME_adj(), ASN1_UTCTIME_adj() and ASN1_GENERALIZEDTIME_adj()
|
||||
functions set the time structure B<s> to the time represented
|
||||
by the time B<offset_day> and B<offset_sec> after the time_t value B<t>.
|
||||
The values of B<offset_day> or B<offset_sec> can be negative to set a
|
||||
time before B<t>. The B<offset_sec> value can also exceed the number of
|
||||
seconds in a day. If B<s> is NULL a new structure is allocated
|
||||
and returned.
|
||||
|
||||
The ASN1_TIME_set_string(), ASN1_UTCTIME_set_string() and
|
||||
ASN1_GENERALIZEDTIME_set_string() functions set the time structure B<s>
|
||||
to the time represented by string B<str> which must be in appropriate ASN.1
|
||||
time format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ). If B<s> is NULL
|
||||
this function performs a format check on B<str> only. The string B<str>
|
||||
is copied into B<s>.
|
||||
|
||||
ASN1_TIME_set_string_X509() sets ASN1_TIME structure B<s> to the time
|
||||
represented by string B<str> which must be in appropriate time format
|
||||
that RFC 5280 requires, which means it only allows YYMMDDHHMMSSZ and
|
||||
YYYYMMDDHHMMSSZ (leap second is rejected), all other ASN.1 time format
|
||||
are not allowed. If B<s> is NULL this function performs a format check
|
||||
on B<str> only.
|
||||
|
||||
The ASN1_TIME_normalize() function converts an ASN1_GENERALIZEDTIME or
|
||||
ASN1_UTCTIME into a time value that can be used in a certificate. It
|
||||
should be used after the ASN1_TIME_set_string() functions and before
|
||||
ASN1_TIME_print() functions to get consistent (i.e. GMT) results.
|
||||
|
||||
The ASN1_TIME_check(), ASN1_UTCTIME_check() and ASN1_GENERALIZEDTIME_check()
|
||||
functions check the syntax of the time structure B<s>.
|
||||
|
||||
The ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print()
|
||||
functions print the time structure B<s> to BIO B<b> in human readable
|
||||
format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
|
||||
"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time
|
||||
structure has invalid format it prints out "Bad time value" and returns
|
||||
an error. The output for generalized time may include a fractional part
|
||||
following the second.
|
||||
|
||||
ASN1_TIME_to_tm() converts the time B<s> to the standard B<tm> structure.
|
||||
If B<s> is NULL, then the current time is converted. The output time is GMT.
|
||||
The B<tm_sec>, B<tm_min>, B<tm_hour>, B<tm_mday>, B<tm_wday>, B<tm_yday>,
|
||||
B<tm_mon> and B<tm_year> fields of B<tm> structure are set to proper values,
|
||||
whereas all other fields are set to 0. If B<tm> is NULL this function performs
|
||||
a format check on B<s> only. If B<s> is in Generalized format with fractional
|
||||
seconds, e.g. YYYYMMDDHHMMSS.SSSZ, the fractional seconds will be lost while
|
||||
converting B<s> to B<tm> structure.
|
||||
|
||||
ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
|
||||
B<from> and B<to>. If B<to> represents a time later than B<from> then
|
||||
one or both (depending on the time difference) of B<*pday> and B<*psec>
|
||||
will be positive. If B<to> represents a time earlier than B<from> then
|
||||
one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
|
||||
represent the same time then B<*pday> and B<*psec> will both be zero.
|
||||
If both B<*pday> and B<*psec> are nonzero they will always have the same
|
||||
sign. The value of B<*psec> will always be less than the number of seconds
|
||||
in a day. If B<from> or B<to> is NULL the current time is used.
|
||||
|
||||
The ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() functions compare
|
||||
the two times represented by the time structure B<s> and the time_t B<t>.
|
||||
|
||||
The ASN1_TIME_compare() function compares the two times represented by the
|
||||
time structures B<a> and B<b>.
|
||||
|
||||
The ASN1_TIME_to_generalizedtime() function converts an ASN1_TIME to an
|
||||
ASN1_GENERALIZEDTIME, regardless of year. If either B<out> or
|
||||
B<*out> are NULL, then a new object is allocated and must be freed after use.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
|
||||
defined in RFC5280 et al. The time setting functions obey the rules outlined
|
||||
in RFC5280: if the date can be represented by UTCTime it is used, else
|
||||
GeneralizedTime is used.
|
||||
|
||||
The ASN1_TIME, ASN1_UTCTIME and ASN1_GENERALIZEDTIME structures are represented
|
||||
as an ASN1_STRING internally and can be freed up using ASN1_STRING_free().
|
||||
|
||||
The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
|
||||
is made to correct ancient calendar changes (for example from Julian to
|
||||
Gregorian calendars).
|
||||
|
||||
ASN1_UTCTIME is limited to a year range of 1950 through 2049.
|
||||
|
||||
Some applications add offset times directly to a time_t value and pass the
|
||||
results to ASN1_TIME_set() (or equivalent). This can cause problems as the
|
||||
time_t value can overflow on some systems resulting in unexpected results.
|
||||
New applications should use ASN1_TIME_adj() instead and pass the offset value
|
||||
in the B<offset_sec> and B<offset_day> parameters instead of directly
|
||||
manipulating a time_t value.
|
||||
|
||||
ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME,
|
||||
or vice versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and
|
||||
ASN1_UTCTIME_adj() functions will not modify the type of the return structure.
|
||||
|
||||
It is recommended that functions starting with ASN1_TIME be used instead of
|
||||
those starting with ASN1_UTCTIME or ASN1_GENERALIZEDTIME. The functions
|
||||
starting with ASN1_UTCTIME and ASN1_GENERALIZEDTIME act only on that specific
|
||||
time format. The functions starting with ASN1_TIME will operate on either
|
||||
format.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print()
|
||||
do not print out the timezone: it either prints out "GMT" or nothing. But all
|
||||
certificates complying with RFC5280 et al use GMT anyway.
|
||||
|
||||
Use the ASN1_TIME_normalize() function to normalize the time value before
|
||||
printing to get GMT results.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(),
|
||||
ASN1_UTCTIME_adj and ASN1_GENERALIZEDTIME_set return a pointer to a time structure
|
||||
or NULL if an error occurred.
|
||||
|
||||
ASN1_TIME_set_string(), ASN1_UTCTIME_set_string(), ASN1_GENERALIZEDTIME_set_string()
|
||||
ASN1_TIME_set_string_X509() return 1 if the time value is successfully set and 0 otherwise.
|
||||
|
||||
ASN1_TIME_normalize() returns 1 on success, and 0 on error.
|
||||
|
||||
ASN1_TIME_check(), ASN1_UTCTIME_check and ASN1_GENERALIZEDTIME_check() return 1
|
||||
if the structure is syntactically correct and 0 otherwise.
|
||||
|
||||
ASN1_TIME_print(), ASN1_UTCTIME_print() and ASN1_GENERALIZEDTIME_print() return 1
|
||||
if the time is successfully printed out and 0 if an error occurred (I/O error or
|
||||
invalid time format).
|
||||
|
||||
ASN1_TIME_to_tm() returns 1 if the time is successfully parsed and 0 if an
|
||||
error occurred (invalid time format).
|
||||
|
||||
ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
|
||||
passed-in time structure has invalid syntax, for example.
|
||||
|
||||
ASN1_TIME_cmp_time_t() and ASN1_UTCTIME_cmp_time_t() return -1 if B<s> is
|
||||
before B<t>, 0 if B<s> equals B<t>, or 1 if B<s> is after B<t>. -2 is returned
|
||||
on error.
|
||||
|
||||
ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or 1 if B<a> is after B<b>. -2 is returned on error.
|
||||
|
||||
ASN1_TIME_to_generalizedtime() returns a pointer to
|
||||
the appropriate time structure on success or NULL if an error occurred.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Set a time structure to one hour after the current time and print it out:
|
||||
|
||||
#include <time.h>
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
ASN1_TIME *tm;
|
||||
time_t t;
|
||||
BIO *b;
|
||||
|
||||
t = time(NULL);
|
||||
tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
|
||||
b = BIO_new_fp(stdout, BIO_NOCLOSE);
|
||||
ASN1_TIME_print(b, tm);
|
||||
ASN1_STRING_free(tm);
|
||||
BIO_free(b);
|
||||
|
||||
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 */
|
||||
|
||||
if (day > 0 || sec > 0)
|
||||
printf("Later\n");
|
||||
else if (day < 0 || sec < 0)
|
||||
printf("Sooner\n");
|
||||
else
|
||||
printf("Same\n");
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1.
|
||||
The ASN1_TIME_set_string_X509() function was added in OpenSSL 1.1.1.
|
||||
The ASN1_TIME_normalize() function was added in OpenSSL 1.1.1.
|
||||
The ASN1_TIME_cmp_time_t() function was added in OpenSSL 1.1.1.
|
||||
The ASN1_TIME_compare() function was added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2015-2020 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
|
||||
@@ -0,0 +1,100 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility
|
||||
functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
int ASN1_TYPE_get(const ASN1_TYPE *a);
|
||||
void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);
|
||||
int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);
|
||||
int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);
|
||||
|
||||
void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);
|
||||
ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s,
|
||||
ASN1_TYPE **t);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
These functions allow an ASN1_TYPE structure to be manipulated. The
|
||||
ASN1_TYPE structure can contain any ASN.1 type or constructed type
|
||||
such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.
|
||||
|
||||
ASN1_TYPE_get() returns the type of B<a>.
|
||||
|
||||
ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This
|
||||
function uses the pointer B<value> internally so it must B<not> be freed
|
||||
up after the call.
|
||||
|
||||
ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>.
|
||||
|
||||
ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if
|
||||
they are identical and nonzero otherwise.
|
||||
|
||||
ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in
|
||||
B<t> using the ASN.1 structure B<it>. If successful it returns a pointer
|
||||
to the ASN.1 structure corresponding to B<it> which must be freed by the
|
||||
caller. If it fails it return NULL.
|
||||
|
||||
ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s>
|
||||
corresponding to B<it> into an ASN1_TYPE. If successful the encoded
|
||||
ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type
|
||||
is written to B<t> overwriting any existing data. If B<t> is not NULL
|
||||
but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The type and meaning of the B<value> parameter for ASN1_TYPE_set() and
|
||||
ASN1_TYPE_set1() is determined by the B<type> parameter.
|
||||
If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN
|
||||
then the boolean is set to TRUE if B<value> is not NULL. If B<type> is
|
||||
V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type>
|
||||
is and ASN1_STRING structure. If B<type> corresponds to a primitive type
|
||||
(or a string type) then the contents of the ASN1_STRING contain the content
|
||||
octets of the type. If B<type> corresponds to a constructed type or
|
||||
a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the
|
||||
ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and
|
||||
length octets).
|
||||
|
||||
ASN1_TYPE_cmp() may not return zero if two types are equivalent but have
|
||||
different encodings. For example the single content octet of the boolean TRUE
|
||||
value under BER can have any nonzero encoding but ASN1_TYPE_cmp() will
|
||||
only return zero if the values are the same.
|
||||
|
||||
If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
|
||||
return value is nonzero. Technically if both parameters are NULL the two
|
||||
types could be absent OPTIONAL fields and so should match, however, passing
|
||||
NULL values could also indicate a programming error (for example an
|
||||
unparsable type which returns NULL) for types which do B<not> match. So
|
||||
applications should handle the case of two absent values separately.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.
|
||||
|
||||
ASN1_TYPE_set() does not return a value.
|
||||
|
||||
ASN1_TYPE_set1() returns 1 for success and 0 for failure.
|
||||
|
||||
ASN1_TYPE_cmp() returns 0 if the types are identical and nonzero otherwise.
|
||||
|
||||
ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or
|
||||
NULL on failure.
|
||||
|
||||
ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or
|
||||
NULL on failure.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2015-2020 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
|
||||
@@ -0,0 +1,270 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
|
||||
ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
These functions generate the ASN1 encoding of a string
|
||||
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 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.
|
||||
|
||||
=head1 GENERATION STRING FORMAT
|
||||
|
||||
The actual data encoded is determined by the string B<str> and
|
||||
the configuration information. The general format of the string
|
||||
is:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<[modifier,]type[:value]>
|
||||
|
||||
=back
|
||||
|
||||
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
|
||||
|
||||
The supported types are listed below. Unless otherwise specified
|
||||
only the B<ASCII> format is permissible.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<BOOLEAN>, B<BOOL>
|
||||
|
||||
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.
|
||||
|
||||
=item B<NULL>
|
||||
|
||||
Encode the B<NULL> type, the B<value> string must not be present.
|
||||
|
||||
=item B<INTEGER>, B<INT>
|
||||
|
||||
Encodes an ASN1 B<INTEGER> type. The B<value> string represents
|
||||
the value of the integer, it can be prefaced by a minus sign and
|
||||
is normally interpreted as a decimal value unless the prefix B<0x>
|
||||
is included.
|
||||
|
||||
=item B<ENUMERATED>, B<ENUM>
|
||||
|
||||
Encodes the ASN1 B<ENUMERATED> type, it is otherwise identical to
|
||||
B<INTEGER>.
|
||||
|
||||
=item B<OBJECT>, B<OID>
|
||||
|
||||
Encodes an ASN1 B<OBJECT IDENTIFIER>, the B<value> string can be
|
||||
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>.
|
||||
|
||||
=item B<GENERALIZEDTIME>, B<GENTIME>
|
||||
|
||||
Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
|
||||
the format B<YYYYMMDDHHMMSSZ>.
|
||||
|
||||
=item B<OCTETSTRING>, B<OCT>
|
||||
|
||||
Encodes an ASN1 B<OCTET STRING>. B<value> represents the contents
|
||||
of this structure, the format strings B<ASCII> and B<HEX> can be
|
||||
used to specify the format of B<value>.
|
||||
|
||||
=item B<BITSTRING>, B<BITSTR>
|
||||
|
||||
Encodes an ASN1 B<BIT STRING>. B<value> represents the contents
|
||||
of this structure, the format strings B<ASCII>, B<HEX> and B<BITLIST>
|
||||
can be used to specify the format of B<value>.
|
||||
|
||||
If the format is anything other than B<BITLIST> the number of unused
|
||||
bits is set to zero.
|
||||
|
||||
=item B<UNIVERSALSTRING>, B<UNIV>, B<IA5>, B<IA5STRING>, B<UTF8>,
|
||||
B<UTF8String>, B<BMP>, B<BMPSTRING>, B<VISIBLESTRING>,
|
||||
B<VISIBLE>, B<PRINTABLESTRING>, B<PRINTABLE>, B<T61>,
|
||||
B<T61STRING>, B<TELETEXSTRING>, B<GeneralString>, B<NUMERICSTRING>,
|
||||
B<NUMERIC>
|
||||
|
||||
These encode the corresponding string types. B<value> represents the
|
||||
contents of this structure. The format can be B<ASCII> or B<UTF8>.
|
||||
|
||||
=item B<SEQUENCE>, B<SEQ>, B<SET>
|
||||
|
||||
Formats the result as an ASN1 B<SEQUENCE> or B<SET> type. B<value>
|
||||
should be a section name which will contain the contents. The
|
||||
field names in the section are ignored and the values are in the
|
||||
generated string format. If B<value> is absent then an empty SEQUENCE
|
||||
will be encoded.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Modifiers
|
||||
|
||||
Modifiers affect the following structure, they can be used to
|
||||
add EXPLICIT or IMPLICIT tagging, add wrappers or to change
|
||||
the string format of the final type and value. The supported
|
||||
formats are documented below.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<EXPLICIT>, B<EXP>
|
||||
|
||||
Add an explicit tag to the following structure. This string
|
||||
should be followed by a colon and the tag value to use as a
|
||||
decimal value.
|
||||
|
||||
By following the number with B<U>, B<A>, B<P> or B<C> UNIVERSAL,
|
||||
APPLICATION, PRIVATE or CONTEXT SPECIFIC tagging can be used,
|
||||
the default is CONTEXT SPECIFIC.
|
||||
|
||||
=item B<IMPLICIT>, B<IMP>
|
||||
|
||||
This is the same as B<EXPLICIT> except IMPLICIT tagging is used
|
||||
instead.
|
||||
|
||||
=item B<OCTWRAP>, B<SEQWRAP>, B<SETWRAP>, B<BITWRAP>
|
||||
|
||||
The following structure is surrounded by an OCTET STRING, a SEQUENCE,
|
||||
a SET or a BIT STRING respectively. For a BIT STRING the number of unused
|
||||
bits is set to zero.
|
||||
|
||||
=item B<FORMAT>
|
||||
|
||||
This specifies the format of the ultimate value. It should be followed
|
||||
by a colon and one of the strings B<ASCII>, B<UTF8>, B<HEX> or B<BITLIST>.
|
||||
|
||||
If no format specifier is included then B<ASCII> is used. If B<UTF8> is
|
||||
specified then the value string must be a valid B<UTF8> string. For B<HEX> the
|
||||
output must be a set of hex digits. B<BITLIST> (which is only valid for a BIT
|
||||
STRING) is a comma separated list of the indices of the set bits, all other
|
||||
bits are zero.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
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)>.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
A simple IA5String:
|
||||
|
||||
IA5STRING:Hello World
|
||||
|
||||
An IA5String explicitly tagged:
|
||||
|
||||
EXPLICIT:0,IA5STRING:Hello World
|
||||
|
||||
An IA5String explicitly tagged using APPLICATION tagging:
|
||||
|
||||
EXPLICIT:0A,IA5STRING:Hello World
|
||||
|
||||
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 consisting of a BOOL an OID and a UTF8String:
|
||||
|
||||
asn1 = SEQUENCE:seq_section
|
||||
|
||||
[seq_section]
|
||||
|
||||
field1 = BOOLEAN:TRUE
|
||||
field2 = OID:commonName
|
||||
field3 = UTF8:Third field
|
||||
|
||||
This example produces an RSAPrivateKey structure, this is the
|
||||
key contained in the file client.pem in all OpenSSL distributions
|
||||
(note: the field names such as 'coeff' are ignored and are present just
|
||||
for clarity):
|
||||
|
||||
asn1=SEQUENCE:private_key
|
||||
[private_key]
|
||||
version=INTEGER:0
|
||||
|
||||
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
|
||||
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
|
||||
|
||||
e=INTEGER:0x010001
|
||||
|
||||
d=INTEGER:0x6F05EAD2F27FFAEC84BEC360C4B928FD5F3A9865D0FCAAD291E2A52F4A\
|
||||
F810DC6373278C006A0ABBA27DC8C63BF97F7E666E27C5284D7D3B1FFFE16B7A87B51D
|
||||
|
||||
p=INTEGER:0xF3929B9435608F8A22C208D86795271D54EBDFB09DDEF539AB083DA912\
|
||||
D4BD57
|
||||
|
||||
q=INTEGER:0xC50016F89DFF2561347ED1186A46E150E28BF2D0F539A1594BBD7FE467\
|
||||
46EC4F
|
||||
|
||||
exp1=INTEGER:0x9E7D4326C924AFC1DEA40B45650134966D6F9DFA3A7F9D698CD4ABEA\
|
||||
9C0A39B9
|
||||
|
||||
exp2=INTEGER:0xBA84003BB95355AFB7C50DF140C60513D0BA51D637272E355E397779\
|
||||
E7B2458F
|
||||
|
||||
coeff=INTEGER:0x30B9E4F2AFA5AC679F920FC83F1F2DF1BAF1779CF989447FABC2F5\
|
||||
628657053A
|
||||
|
||||
This example is the corresponding public key in a SubjectPublicKeyInfo
|
||||
structure:
|
||||
|
||||
# Start with a SEQUENCE
|
||||
asn1=SEQUENCE:pubkeyinfo
|
||||
|
||||
# pubkeyinfo contains an algorithm identifier and the public key wrapped
|
||||
# in a BIT STRING
|
||||
[pubkeyinfo]
|
||||
algorithm=SEQUENCE:rsa_alg
|
||||
pubkey=BITWRAP,SEQUENCE:rsapubkey
|
||||
|
||||
# algorithm ID for RSA is just an OID and a NULL
|
||||
[rsa_alg]
|
||||
algorithm=OID:rsaEncryption
|
||||
parameter=NULL
|
||||
|
||||
# Actual public key: modulus and exponent
|
||||
[rsapubkey]
|
||||
n=INTEGER:0xBB6FE79432CC6EA2D8F970675A5A87BFBE1AFF0BE63E879F2AFFB93644\
|
||||
D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
|
||||
|
||||
e=INTEGER:0x010001
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2002-2019 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
|
||||
@@ -0,0 +1,144 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
|
||||
ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
|
||||
ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage
|
||||
waiting for asynchronous jobs to complete
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/async.h>
|
||||
|
||||
ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
|
||||
void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
|
||||
int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
|
||||
OSSL_ASYNC_FD fd,
|
||||
void *custom_data,
|
||||
void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
|
||||
OSSL_ASYNC_FD, void *));
|
||||
int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
|
||||
OSSL_ASYNC_FD *fd, void **custom_data);
|
||||
int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
|
||||
size_t *numfds);
|
||||
int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
|
||||
size_t *numaddfds, OSSL_ASYNC_FD *delfd,
|
||||
size_t *numdelfds);
|
||||
int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
|
||||
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
For an overview of how asynchronous operations are implemented in OpenSSL see
|
||||
L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous
|
||||
"session", i.e. a related set of crypto operations. For example in SSL terms
|
||||
this would have a one-to-one correspondence with an SSL connection.
|
||||
|
||||
Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new()
|
||||
function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
|
||||
the job is started it is associated with the ASYNC_WAIT_CTX for the duration of
|
||||
that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one
|
||||
time, but can be reused after an ASYNC_JOB has finished for a subsequent
|
||||
ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed),
|
||||
application code cleans up with ASYNC_WAIT_CTX_free().
|
||||
|
||||
ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling
|
||||
ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in
|
||||
the B<ctx> parameter will return the wait file descriptors associated with that
|
||||
job in B<*fd>. The number of file descriptors returned will be stored in
|
||||
B<*numfds>. It is the caller's responsibility to ensure that sufficient memory
|
||||
has been allocated in B<*fd> to receive all the file descriptors. Calling
|
||||
ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file
|
||||
descriptors but will still populate B<*numfds>. Therefore, application code is
|
||||
typically expected to call this function twice: once to get the number of fds,
|
||||
and then again when sufficient memory has been allocated. If only one
|
||||
asynchronous engine is being used then normally this call will only ever return
|
||||
one fd. If multiple asynchronous engines are being used then more could be
|
||||
returned.
|
||||
|
||||
The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds
|
||||
have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE
|
||||
result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has
|
||||
been received). The B<numaddfds> and B<numdelfds> parameters will be populated
|
||||
with the number of fds added or deleted respectively. B<*addfd> and B<*delfd>
|
||||
will be populated with the list of added and deleted fds respectively. Similarly
|
||||
to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
|
||||
NULL then the caller is responsible for ensuring sufficient memory is allocated.
|
||||
|
||||
Implementors of async aware code (e.g. engines) are encouraged to return a
|
||||
stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn"
|
||||
of regularly changing fds - although no guarantees of this are provided to
|
||||
applications.
|
||||
|
||||
Applications can wait for the file descriptor to be ready for "read" using a
|
||||
system function call such as select or poll (being ready for "read" indicates
|
||||
that the job should be resumed). If no file descriptor is made available then an
|
||||
application will have to periodically "poll" the job by attempting to restart it
|
||||
to see if it is ready to continue.
|
||||
|
||||
Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job
|
||||
via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting
|
||||
on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an
|
||||
engine immediately prior to calling ASYNC_pause_job() and not by end user code.
|
||||
An existing association with a file descriptor can be obtained using
|
||||
ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
|
||||
these functions requires a B<key> value which is unique to the async aware
|
||||
code. This could be any unique value but a good candidate might be the
|
||||
B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and
|
||||
will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
|
||||
ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
|
||||
routine. This can be NULL but if provided will automatically get called when
|
||||
the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the
|
||||
fd or any other resources. Note: The "cleanup" routine does not get called if
|
||||
the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
|
||||
|
||||
An example of typical usage might be an async capable engine. User code would
|
||||
initiate cryptographic operations. The engine would initiate those operations
|
||||
asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
|
||||
ASYNC_pause_job() to return control to the user code. The user code can then
|
||||
perform other tasks or wait for the job to be ready by calling "select" or other
|
||||
similar function on the wait file descriptor. The engine can signal to the user
|
||||
code that the job should be resumed by making the wait file descriptor
|
||||
"readable". Once resumed the engine should clear the wake signal on the wait
|
||||
file descriptor.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
|
||||
NULL on error.
|
||||
|
||||
ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
|
||||
ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
|
||||
success or 0 on error.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
On Windows platforms the openssl/async.h header is dependent on some
|
||||
of the types customarily made available by including windows.h. The
|
||||
application developer is likely to require control over when the latter
|
||||
is included, commonly as one of the first included headers. Therefore,
|
||||
it is defined as an application developer's responsibility to include
|
||||
windows.h prior to async.h.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<crypto(7)>, L<ASYNC_start_job(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
ASYNC_WAIT_CTX_new(), ASYNC_WAIT_CTX_free(), ASYNC_WAIT_CTX_set_wait_fd(),
|
||||
ASYNC_WAIT_CTX_get_fd(), ASYNC_WAIT_CTX_get_all_fds(),
|
||||
ASYNC_WAIT_CTX_get_changed_fds() and ASYNC_WAIT_CTX_clear_fd()
|
||||
were added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2020 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
|
||||
@@ -0,0 +1,331 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASYNC_get_wait_ctx,
|
||||
ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job,
|
||||
ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
|
||||
- asynchronous job management functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/async.h>
|
||||
|
||||
int ASYNC_init_thread(size_t max_size, size_t init_size);
|
||||
void ASYNC_cleanup_thread(void);
|
||||
|
||||
int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,
|
||||
int (*func)(void *), void *args, size_t size);
|
||||
int ASYNC_pause_job(void);
|
||||
|
||||
ASYNC_JOB *ASYNC_get_current_job(void);
|
||||
ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);
|
||||
void ASYNC_block_pause(void);
|
||||
void ASYNC_unblock_pause(void);
|
||||
|
||||
int ASYNC_is_capable(void);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This
|
||||
represents code that can be started and executes until some event occurs. At
|
||||
that point the code can be paused and control returns to user code until some
|
||||
subsequent event indicates that the job can be resumed.
|
||||
|
||||
The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for
|
||||
efficiency reasons, jobs can be created up front and reused many times. They are
|
||||
held in a pool until they are needed, at which point they are removed from the
|
||||
pool, used, and then returned to the pool when the job completes. If the user
|
||||
application is multi-threaded, then ASYNC_init_thread() may be called for each
|
||||
thread that will initiate asynchronous jobs. Before
|
||||
user code exits per-thread resources need to be cleaned up. This will normally
|
||||
occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly
|
||||
initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be
|
||||
outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to
|
||||
ensure this will result in memory leaks.
|
||||
|
||||
The B<max_size> argument limits the number of ASYNC_JOBs that will be held in
|
||||
the pool. If B<max_size> is set to 0 then no upper limit is set. When an
|
||||
ASYNC_JOB is needed but there are none available in the pool already then one
|
||||
will be automatically created, as long as the total of ASYNC_JOBs managed by the
|
||||
pool does not exceed B<max_size>. When the pool is first initialised
|
||||
B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is
|
||||
not called before the pool is first used then it will be called automatically
|
||||
with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs
|
||||
created up front).
|
||||
|
||||
An asynchronous job is started by calling the ASYNC_start_job() function.
|
||||
Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX
|
||||
object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should
|
||||
point to a location where the return value of the asynchronous function should
|
||||
be stored on completion of the job. B<func> represents the function that should
|
||||
be started asynchronously. The data pointed to by B<args> and of size B<size>
|
||||
will be copied and then passed as an argument to B<func> when the job starts.
|
||||
ASYNC_start_job will return one of the following values:
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<ASYNC_ERR>
|
||||
|
||||
An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
|
||||
see L<ERR_print_errors(3)>) for more details.
|
||||
|
||||
=item B<ASYNC_NO_JOBS>
|
||||
|
||||
There are no jobs currently available in the pool. This call can be retried
|
||||
again at a later time.
|
||||
|
||||
=item B<ASYNC_PAUSE>
|
||||
|
||||
The job was successfully started but was "paused" before it completed (see
|
||||
ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work
|
||||
can be performed (if desired) and the job restarted at a later time. To restart
|
||||
a job call ASYNC_start_job() again passing the job handle in B<*job>. The
|
||||
B<func>, B<args> and B<size> parameters will be ignored when restarting a job.
|
||||
When restarting a job ASYNC_start_job() B<must> be called from the same thread
|
||||
that the job was originally started from.
|
||||
|
||||
=item B<ASYNC_FINISH>
|
||||
|
||||
The job completed. B<*job> will be NULL and the return value from B<func> will
|
||||
be placed in B<*ret>.
|
||||
|
||||
=back
|
||||
|
||||
At any one time there can be a maximum of one job actively running per thread
|
||||
(you can have many that are paused). ASYNC_get_current_job() can be used to get
|
||||
a pointer to the currently executing ASYNC_JOB. If no job is currently executing
|
||||
then this will return NULL.
|
||||
|
||||
If executing within the context of a job (i.e. having been called directly or
|
||||
indirectly by the function "func" passed as an argument to ASYNC_start_job())
|
||||
then ASYNC_pause_job() will immediately return control to the calling
|
||||
application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A
|
||||
subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the
|
||||
B<*job> parameter will resume execution from the ASYNC_pause_job() call. If
|
||||
ASYNC_pause_job() is called whilst not within the context of a job then no
|
||||
action is taken and ASYNC_pause_job() returns immediately.
|
||||
|
||||
ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX
|
||||
for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated
|
||||
with them. Applications can wait for the file descriptor to be ready for "read"
|
||||
using a system function call such as select or poll (being ready for "read"
|
||||
indicates that the job should be resumed). If no file descriptor is made
|
||||
available then an application will have to periodically "poll" the job by
|
||||
attempting to restart it to see if it is ready to continue.
|
||||
|
||||
An example of typical usage might be an async capable engine. User code would
|
||||
initiate cryptographic operations. The engine would initiate those operations
|
||||
asynchronously and then call L<ASYNC_WAIT_CTX_set_wait_fd(3)> followed by
|
||||
ASYNC_pause_job() to return control to the user code. The user code can then
|
||||
perform other tasks or wait for the job to be ready by calling "select" or other
|
||||
similar function on the wait file descriptor. The engine can signal to the user
|
||||
code that the job should be resumed by making the wait file descriptor
|
||||
"readable". Once resumed the engine should clear the wake signal on the wait
|
||||
file descriptor.
|
||||
|
||||
The ASYNC_block_pause() function will prevent the currently active job from
|
||||
pausing. The block will remain in place until a subsequent call to
|
||||
ASYNC_unblock_pause(). These functions can be nested, e.g. if you call
|
||||
ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in
|
||||
order to re-enable pausing. If these functions are called while there is no
|
||||
currently active job then they have no effect. This functionality can be useful
|
||||
to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an
|
||||
application acquires a lock. It then calls some cryptographic function which
|
||||
invokes ASYNC_pause_job(). This returns control back to the code that created
|
||||
the ASYNC_JOB. If that code then attempts to acquire the same lock before
|
||||
resuming the original job then a deadlock can occur. By calling
|
||||
ASYNC_block_pause() immediately after acquiring the lock and
|
||||
ASYNC_unblock_pause() immediately before releasing it then this situation cannot
|
||||
occur.
|
||||
|
||||
Some platforms cannot support async operations. The ASYNC_is_capable() function
|
||||
can be used to detect whether the current platform is async capable or not.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASYNC_init_thread returns 1 on success or 0 otherwise.
|
||||
|
||||
ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or
|
||||
ASYNC_FINISH as described above.
|
||||
|
||||
ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
|
||||
not within the context of an ASYNC_JOB then this is counted as success so 1 is
|
||||
returned.
|
||||
|
||||
ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or
|
||||
NULL if not within the context of a job.
|
||||
|
||||
ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.
|
||||
|
||||
ASYNC_is_capable() returns 1 if the current platform is async capable or 0
|
||||
otherwise.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
On Windows platforms the openssl/async.h header is dependent on some
|
||||
of the types customarily made available by including windows.h. The
|
||||
application developer is likely to require control over when the latter
|
||||
is included, commonly as one of the first included headers. Therefore,
|
||||
it is defined as an application developer's responsibility to include
|
||||
windows.h prior to async.h.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
The following example demonstrates how to use most of the core async APIs:
|
||||
|
||||
#ifdef _WIN32
|
||||
# include <windows.h>
|
||||
#endif
|
||||
#include <stdio.h>
|
||||
#include <unistd.h>
|
||||
#include <openssl/async.h>
|
||||
#include <openssl/crypto.h>
|
||||
|
||||
int unique = 0;
|
||||
|
||||
void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
|
||||
{
|
||||
OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;
|
||||
|
||||
close(r);
|
||||
close(*w);
|
||||
OPENSSL_free(w);
|
||||
}
|
||||
|
||||
int jobfunc(void *arg)
|
||||
{
|
||||
ASYNC_JOB *currjob;
|
||||
unsigned char *msg;
|
||||
int pipefds[2] = {0, 0};
|
||||
OSSL_ASYNC_FD *wptr;
|
||||
char buf = 'X';
|
||||
|
||||
currjob = ASYNC_get_current_job();
|
||||
if (currjob != NULL) {
|
||||
printf("Executing within a job\n");
|
||||
} else {
|
||||
printf("Not executing within a job - should not happen\n");
|
||||
return 0;
|
||||
}
|
||||
|
||||
msg = (unsigned char *)arg;
|
||||
printf("Passed in message is: %s\n", msg);
|
||||
|
||||
if (pipe(pipefds) != 0) {
|
||||
printf("Failed to create pipe\n");
|
||||
return 0;
|
||||
}
|
||||
wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
|
||||
if (wptr == NULL) {
|
||||
printf("Failed to malloc\n");
|
||||
return 0;
|
||||
}
|
||||
*wptr = pipefds[1];
|
||||
ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,
|
||||
pipefds[0], wptr, cleanup);
|
||||
|
||||
/*
|
||||
* Normally some external event would cause this to happen at some
|
||||
* later point - but we do it here for demo purposes, i.e.
|
||||
* immediately signalling that the job is ready to be woken up after
|
||||
* we return to main via ASYNC_pause_job().
|
||||
*/
|
||||
write(pipefds[1], &buf, 1);
|
||||
|
||||
/* Return control back to main */
|
||||
ASYNC_pause_job();
|
||||
|
||||
/* Clear the wake signal */
|
||||
read(pipefds[0], &buf, 1);
|
||||
|
||||
printf ("Resumed the job after a pause\n");
|
||||
|
||||
return 1;
|
||||
}
|
||||
|
||||
int main(void)
|
||||
{
|
||||
ASYNC_JOB *job = NULL;
|
||||
ASYNC_WAIT_CTX *ctx = NULL;
|
||||
int ret;
|
||||
OSSL_ASYNC_FD waitfd;
|
||||
fd_set waitfdset;
|
||||
size_t numfds;
|
||||
unsigned char msg[13] = "Hello world!";
|
||||
|
||||
printf("Starting...\n");
|
||||
|
||||
ctx = ASYNC_WAIT_CTX_new();
|
||||
if (ctx == NULL) {
|
||||
printf("Failed to create ASYNC_WAIT_CTX\n");
|
||||
abort();
|
||||
}
|
||||
|
||||
for (;;) {
|
||||
switch (ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
|
||||
case ASYNC_ERR:
|
||||
case ASYNC_NO_JOBS:
|
||||
printf("An error occurred\n");
|
||||
goto end;
|
||||
case ASYNC_PAUSE:
|
||||
printf("Job was paused\n");
|
||||
break;
|
||||
case ASYNC_FINISH:
|
||||
printf("Job finished with return value %d\n", ret);
|
||||
goto end;
|
||||
}
|
||||
|
||||
/* Wait for the job to be woken */
|
||||
printf("Waiting for the job to be woken up\n");
|
||||
|
||||
if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
|
||||
|| numfds > 1) {
|
||||
printf("Unexpected number of fds\n");
|
||||
abort();
|
||||
}
|
||||
ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);
|
||||
FD_ZERO(&waitfdset);
|
||||
FD_SET(waitfd, &waitfdset);
|
||||
select(waitfd + 1, &waitfdset, NULL, NULL, NULL);
|
||||
}
|
||||
|
||||
end:
|
||||
ASYNC_WAIT_CTX_free(ctx);
|
||||
printf("Finishing\n");
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
The expected output from executing the above example program is:
|
||||
|
||||
Starting...
|
||||
Executing within a job
|
||||
Passed in message is: Hello world!
|
||||
Job was paused
|
||||
Waiting for the job to be woken up
|
||||
Resumed the job after a pause
|
||||
Job finished with return value 1
|
||||
Finishing
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<crypto(7)>, L<ERR_print_errors(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
ASYNC_init_thread, ASYNC_cleanup_thread,
|
||||
ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(),
|
||||
ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first
|
||||
added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2015-2020 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
|
||||
@@ -0,0 +1,119 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
|
||||
BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/blowfish.h>
|
||||
|
||||
void BF_set_key(BF_KEY *key, int len, const unsigned char *data);
|
||||
|
||||
void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
|
||||
BF_KEY *key, int enc);
|
||||
void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
|
||||
long length, BF_KEY *schedule,
|
||||
unsigned char *ivec, int enc);
|
||||
void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
|
||||
long length, BF_KEY *schedule,
|
||||
unsigned char *ivec, int *num, int enc);
|
||||
void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
|
||||
long length, BF_KEY *schedule,
|
||||
unsigned char *ivec, int *num);
|
||||
const char *BF_options(void);
|
||||
|
||||
void BF_encrypt(BF_LONG *data, const BF_KEY *key);
|
||||
void BF_decrypt(BF_LONG *data, const BF_KEY *key);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
This library implements the Blowfish cipher, which was invented and described
|
||||
by Counterpane (see http://www.counterpane.com/blowfish.html ).
|
||||
|
||||
Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
|
||||
It uses a variable size key, but typically, 128 bit (16 byte) keys are
|
||||
considered good for strong encryption. Blowfish can be used in the same
|
||||
modes as DES (see L<des_modes(7)>). Blowfish is currently one
|
||||
of the faster block ciphers. It is quite a bit faster than DES, and much
|
||||
faster than IDEA or RC2.
|
||||
|
||||
Blowfish consists of a key setup phase and the actual encryption or decryption
|
||||
phase.
|
||||
|
||||
BF_set_key() sets up the B<BF_KEY> B<key> using the B<len> bytes long key
|
||||
at B<data>.
|
||||
|
||||
BF_ecb_encrypt() is the basic Blowfish encryption and decryption function.
|
||||
It encrypts or decrypts the first 64 bits of B<in> using the key B<key>,
|
||||
putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
|
||||
or decryption (B<BF_DECRYPT>) shall be performed. The vector pointed at by
|
||||
B<in> and B<out> must be 64 bits in length, no less. If they are larger,
|
||||
everything after the first 64 bits is ignored.
|
||||
|
||||
The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
|
||||
all operate on variable length data. They all take an initialization vector
|
||||
B<ivec> which needs to be passed along into the next call of the same function
|
||||
for the same message. B<ivec> may be initialized with anything, but the
|
||||
recipient needs to know what it was initialized with, or it won't be able
|
||||
to decrypt. Some programs and protocols simplify this, like SSH, where
|
||||
B<ivec> is simply initialized to zero.
|
||||
BF_cbc_encrypt() operates on data that is a multiple of 8 bytes long, while
|
||||
BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt a variable
|
||||
number of bytes (the amount does not have to be an exact multiple of 8). The
|
||||
purpose of the latter two is to simulate stream ciphers, and therefore, they
|
||||
need the parameter B<num>, which is a pointer to an integer where the current
|
||||
offset in B<ivec> is stored between calls. This integer must be initialized
|
||||
to zero when B<ivec> is initialized.
|
||||
|
||||
BF_cbc_encrypt() is the Cipher Block Chaining function for Blowfish. It
|
||||
encrypts or decrypts the 64 bits chunks of B<in> using the key B<schedule>,
|
||||
putting the result in B<out>. B<enc> decides if encryption (BF_ENCRYPT) or
|
||||
decryption (BF_DECRYPT) shall be performed. B<ivec> must point at an 8 byte
|
||||
long initialization vector.
|
||||
|
||||
BF_cfb64_encrypt() is the CFB mode for Blowfish with 64 bit feedback.
|
||||
It encrypts or decrypts the bytes in B<in> using the key B<schedule>,
|
||||
putting the result in B<out>. B<enc> decides if encryption (B<BF_ENCRYPT>)
|
||||
or decryption (B<BF_DECRYPT>) shall be performed. B<ivec> must point at an
|
||||
8 byte long initialization vector. B<num> must point at an integer which must
|
||||
be initially zero.
|
||||
|
||||
BF_ofb64_encrypt() is the OFB mode for Blowfish with 64 bit feedback.
|
||||
It uses the same parameters as BF_cfb64_encrypt(), which must be initialized
|
||||
the same way.
|
||||
|
||||
BF_encrypt() and BF_decrypt() are the lowest level functions for Blowfish
|
||||
encryption. They encrypt/decrypt the first 64 bits of the vector pointed by
|
||||
B<data>, using the key B<key>. These functions should not be used unless you
|
||||
implement 'modes' of Blowfish. The alternative is to use BF_ecb_encrypt().
|
||||
If you still want to use these functions, you should be aware that they take
|
||||
each 32-bit chunk in host-byte order, which is little-endian on little-endian
|
||||
platforms and big-endian on big-endian ones.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
None of the functions presented here return any value.
|
||||
|
||||
=head1 NOTE
|
||||
|
||||
Applications should use the higher level functions
|
||||
L<EVP_EncryptInit(3)> etc. instead of calling these
|
||||
functions directly.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_EncryptInit(3)>,
|
||||
L<des_modes(7)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,125 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake,
|
||||
BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
|
||||
BIO_ADDR_hostname_string, BIO_ADDR_service_string,
|
||||
BIO_ADDR_path_string - BIO_ADDR routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <sys/types.h>
|
||||
#include <openssl/bio.h>
|
||||
|
||||
typedef union bio_addr_st BIO_ADDR;
|
||||
|
||||
BIO_ADDR *BIO_ADDR_new(void);
|
||||
void BIO_ADDR_free(BIO_ADDR *);
|
||||
void BIO_ADDR_clear(BIO_ADDR *ap);
|
||||
int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
|
||||
const void *where, size_t wherelen, unsigned short port);
|
||||
int BIO_ADDR_family(const BIO_ADDR *ap);
|
||||
int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
|
||||
unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
|
||||
char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
|
||||
char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
|
||||
char *BIO_ADDR_path_string(const BIO_ADDR *ap);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<BIO_ADDR> type is a wrapper around all types of socket
|
||||
addresses that OpenSSL deals with, currently transparently
|
||||
supporting AF_INET, AF_INET6 and AF_UNIX according to what's
|
||||
available on the platform at hand.
|
||||
|
||||
BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
|
||||
with routines that will fill it with information, such as
|
||||
BIO_accept_ex().
|
||||
|
||||
BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new().
|
||||
|
||||
BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
|
||||
it back to an uninitialised state.
|
||||
|
||||
BIO_ADDR_rawmake() takes a protocol B<family>, a byte array of
|
||||
size B<wherelen> with an address in network byte order pointed at
|
||||
by B<where> and a port number in network byte order in B<port> (except
|
||||
for the B<AF_UNIX> protocol family, where B<port> is meaningless and
|
||||
therefore ignored) and populates the given B<BIO_ADDR> with them.
|
||||
In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected
|
||||
to be the length of the path string (not including the terminating
|
||||
NUL, such as the result of a call to strlen()).
|
||||
I<Read on about the addresses in L</RAW ADDRESSES> below>.
|
||||
|
||||
BIO_ADDR_family() returns the protocol family of the given
|
||||
B<BIO_ADDR>. The possible non-error results are one of the
|
||||
constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the
|
||||
BIO_ADDR has not been initialised.
|
||||
|
||||
BIO_ADDR_rawaddress() will write the raw address of the given
|
||||
B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL,
|
||||
and will set B<*l> to be the amount of bytes the raw address
|
||||
takes up if B<l> is non-NULL.
|
||||
A technique to only find out the size of the address is a call
|
||||
with B<p> set to B<NULL>. The raw address will be in network byte
|
||||
order, most significant byte first.
|
||||
In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the
|
||||
path string (not including the terminating NUL, such as the result of
|
||||
a call to strlen()).
|
||||
I<Read on about the addresses in L</RAW ADDRESSES> below>.
|
||||
|
||||
BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>.
|
||||
The raw port will be in network byte order.
|
||||
|
||||
BIO_ADDR_hostname_string() returns a character string with the
|
||||
hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string
|
||||
will contain the numerical form of the address. This only works for
|
||||
B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
|
||||
returned string has been allocated on the heap and must be freed
|
||||
with OPENSSL_free().
|
||||
|
||||
BIO_ADDR_service_string() returns a character string with the
|
||||
service name of the port of the given B<BIO_ADDR>. If B<numeric>
|
||||
is 1, the string will contain the port number. This only works
|
||||
for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
|
||||
returned string has been allocated on the heap and must be freed
|
||||
with OPENSSL_free().
|
||||
|
||||
BIO_ADDR_path_string() returns a character string with the path
|
||||
of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the
|
||||
protocol family AF_UNIX. The returned string has been allocated
|
||||
on the heap and must be freed with OPENSSL_free().
|
||||
|
||||
=head1 RAW ADDRESSES
|
||||
|
||||
Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a
|
||||
network byte order address of a specific site. Internally, those are
|
||||
treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct
|
||||
in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all
|
||||
depending on the protocol family the address is for.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The string producing functions BIO_ADDR_hostname_string(),
|
||||
BIO_ADDR_service_string() and BIO_ADDR_path_string() will
|
||||
return B<NULL> on error and leave an error indication on the
|
||||
OpenSSL error stack.
|
||||
|
||||
All other functions described here return 0 or B<NULL> when the
|
||||
information they should return isn't available.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_connect(3)>, L<BIO_s_connect(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2020 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
|
||||
@@ -0,0 +1,114 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_lookup_type,
|
||||
BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
|
||||
BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
|
||||
BIO_ADDRINFO_address,
|
||||
BIO_lookup_ex,
|
||||
BIO_lookup
|
||||
- BIO_ADDRINFO type and routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <sys/types.h>
|
||||
#include <openssl/bio.h>
|
||||
|
||||
typedef union bio_addrinfo_st BIO_ADDRINFO;
|
||||
|
||||
enum BIO_lookup_type {
|
||||
BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
|
||||
};
|
||||
|
||||
int BIO_lookup_ex(const char *host, const char *service, int lookup_type,
|
||||
int family, int socktype, int protocol, BIO_ADDRINFO **res);
|
||||
int BIO_lookup(const char *node, const char *service,
|
||||
enum BIO_lookup_type lookup_type,
|
||||
int family, int socktype, BIO_ADDRINFO **res);
|
||||
|
||||
const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
|
||||
int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
|
||||
int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
|
||||
int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
|
||||
const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
|
||||
void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<BIO_ADDRINFO> type is a wrapper for address information
|
||||
types provided on your platform.
|
||||
|
||||
B<BIO_ADDRINFO> normally forms a chain of several that can be
|
||||
picked at one by one.
|
||||
|
||||
BIO_lookup_ex() looks up a specified B<host> and B<service>, and
|
||||
uses B<lookup_type> to determine what the default address should
|
||||
be if B<host> is B<NULL>. B<family>, B<socktype> and B<protocol> are used to
|
||||
determine what protocol family, socket type and protocol should be used for
|
||||
the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
|
||||
AF_UNSPEC. B<socktype> can be SOCK_STREAM, SOCK_DGRAM or 0. Specifying 0
|
||||
indicates that any type can be used. B<protocol> specifies a protocol such as
|
||||
IPPROTO_TCP, IPPROTO_UDP or IPPORTO_SCTP. If set to 0 than any protocol can be
|
||||
used. B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
|
||||
chain.
|
||||
|
||||
For the family B<AF_UNIX>, BIO_lookup_ex() will ignore the B<service>
|
||||
parameter and expects the B<node> parameter to hold the path to the
|
||||
socket file.
|
||||
|
||||
BIO_lookup() does the same as BIO_lookup_ex() but does not provide the ability
|
||||
to select based on the protocol (any protocol may be returned).
|
||||
|
||||
BIO_ADDRINFO_family() returns the family of the given
|
||||
B<BIO_ADDRINFO>. The result will be one of the constants
|
||||
AF_INET, AF_INET6 and AF_UNIX.
|
||||
|
||||
BIO_ADDRINFO_socktype() returns the socket type of the given
|
||||
B<BIO_ADDRINFO>. The result will be one of the constants
|
||||
SOCK_STREAM and SOCK_DGRAM.
|
||||
|
||||
BIO_ADDRINFO_protocol() returns the protocol id of the given
|
||||
B<BIO_ADDRINFO>. The result will be one of the constants
|
||||
IPPROTO_TCP and IPPROTO_UDP.
|
||||
|
||||
BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR>
|
||||
of the given B<BIO_ADDRINFO>.
|
||||
|
||||
BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain
|
||||
from the given one.
|
||||
|
||||
BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
|
||||
with the given one.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_lookup_ex() and BIO_lookup() return 1 on success and 0 when an error
|
||||
occurred, and will leave an error indication on the OpenSSL error stack in that
|
||||
case.
|
||||
|
||||
All other functions described here return 0 or B<NULL> when the
|
||||
information they should return isn't available.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The BIO_lookup_ex() implementation uses the platform provided getaddrinfo()
|
||||
function. On Linux it is known that specifying 0 for the protocol will not
|
||||
return any SCTP based addresses when calling getaddrinfo(). Therefore, if an SCTP
|
||||
address is required then the B<protocol> parameter to BIO_lookup_ex() should be
|
||||
explicitly set to IPPROTO_SCTP. The same may be true on other platforms.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The BIO_lookup_ex() function was added in OpenSSL 1.1.1.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2020 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
|
||||
@@ -0,0 +1,117 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
|
||||
socket communication setup routines
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
int BIO_socket(int domain, int socktype, int protocol, int options);
|
||||
int BIO_bind(int sock, const BIO_ADDR *addr, int options);
|
||||
int BIO_connect(int sock, const BIO_ADDR *addr, int options);
|
||||
int BIO_listen(int sock, const BIO_ADDR *addr, int options);
|
||||
int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);
|
||||
int BIO_closesocket(int sock);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_socket() creates a socket in the domain B<domain>, of type
|
||||
B<socktype> and B<protocol>. Socket B<options> are currently unused,
|
||||
but is present for future use.
|
||||
|
||||
BIO_bind() binds the source address and service to a socket and
|
||||
may be useful before calling BIO_connect(). The options may include
|
||||
B<BIO_SOCK_REUSEADDR>, which is described in L</FLAGS> below.
|
||||
|
||||
BIO_connect() connects B<sock> to the address and service given by
|
||||
B<addr>. Connection B<options> may be zero or any combination of
|
||||
B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>.
|
||||
The flags are described in L</FLAGS> below.
|
||||
|
||||
BIO_listen() has B<sock> start listening on the address and service
|
||||
given by B<addr>. Connection B<options> may be zero or any
|
||||
combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>,
|
||||
B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>.
|
||||
The flags are described in L</FLAGS> below.
|
||||
|
||||
BIO_accept_ex() waits for an incoming connections on the given
|
||||
socket B<accept_sock>. When it gets a connection, the address and
|
||||
port of the peer gets stored in B<peer> if that one is non-NULL.
|
||||
Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied
|
||||
on the accepted socket. The flags are described in L</FLAGS> below.
|
||||
|
||||
BIO_closesocket() closes B<sock>.
|
||||
|
||||
=head1 FLAGS
|
||||
|
||||
=over 4
|
||||
|
||||
=item BIO_SOCK_KEEPALIVE
|
||||
|
||||
Enables regular sending of keep-alive messages.
|
||||
|
||||
=item BIO_SOCK_NONBLOCK
|
||||
|
||||
Sets the socket to nonblocking mode.
|
||||
|
||||
=item BIO_SOCK_NODELAY
|
||||
|
||||
Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With
|
||||
this set, any data will be sent as soon as possible instead of being
|
||||
buffered until there's enough for the socket to send out in one go.
|
||||
|
||||
=item BIO_SOCK_REUSEADDR
|
||||
|
||||
Try to reuse the address and port combination for a recently closed
|
||||
port.
|
||||
|
||||
=item BIO_SOCK_V6_ONLY
|
||||
|
||||
When creating an IPv6 socket, make it only listen for IPv6 addresses
|
||||
and not IPv4 addresses mapped to IPv6.
|
||||
|
||||
=back
|
||||
|
||||
These flags are bit flags, so they are to be combined with the
|
||||
C<|> operator, for example:
|
||||
|
||||
BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_socket() returns the socket number on success or B<INVALID_SOCKET>
|
||||
(-1) on error. When an error has occurred, the OpenSSL error stack
|
||||
will hold the error data and errno has the system error.
|
||||
|
||||
BIO_bind(), BIO_connect() and BIO_listen() return 1 on success or 0 on error.
|
||||
When an error has occurred, the OpenSSL error stack will hold the error
|
||||
data and errno has the system error.
|
||||
|
||||
BIO_accept_ex() returns the accepted socket on success or
|
||||
B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
|
||||
OpenSSL error stack will hold the error data and errno has the system
|
||||
error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_ADDR(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
|
||||
BIO_get_accept_socket() and BIO_accept() were deprecated in OpenSSL 1.1.0.
|
||||
Use the functions described above instead.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2020 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
|
||||
@@ -0,0 +1,136 @@
|
||||
=pod
|
||||
|
||||
=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_info_cb
|
||||
- BIO control operations
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
typedef int BIO_info_cb(BIO *b, int state, int res);
|
||||
|
||||
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_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);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
|
||||
are BIO "control" operations taking arguments of various types.
|
||||
These functions are not normally called directly, various macros
|
||||
are used instead. The standard macros are described below, macros
|
||||
specific to a particular type of BIO are described in the specific
|
||||
BIOs manual page as well as any special features of the standard
|
||||
calls.
|
||||
|
||||
BIO_reset() typically resets a BIO to some initial state, in the case
|
||||
of file related BIOs for example it rewinds the file pointer to the
|
||||
start of the file.
|
||||
|
||||
BIO_seek() resets a file related BIO's (that is file descriptor and
|
||||
FILE BIOs) file position pointer to B<ofs> bytes from start of file.
|
||||
|
||||
BIO_tell() returns the current file position of a file related BIO.
|
||||
|
||||
BIO_flush() normally writes out any internally buffered data, in some
|
||||
cases it is used to signal EOF and that no more data will be written.
|
||||
|
||||
BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of
|
||||
"EOF" varies according to the BIO type.
|
||||
|
||||
BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can
|
||||
take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
|
||||
in a source/sink BIO to indicate that the underlying I/O stream should
|
||||
be closed when the BIO is freed.
|
||||
|
||||
BIO_get_close() returns the BIOs close flag.
|
||||
|
||||
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
|
||||
return the number of pending characters in the BIOs read and write buffers.
|
||||
Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending()
|
||||
return a size_t type and are functions, BIO_pending() and BIO_wpending() are
|
||||
macros which call BIO_ctrl().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
|
||||
BIOs are an exception, they return 0 for success and -1 for failure.
|
||||
|
||||
BIO_seek() and BIO_tell() both return the current file position on success
|
||||
and -1 for failure, except file BIOs which for BIO_seek() always return 0
|
||||
for success and -1 for failure.
|
||||
|
||||
BIO_flush() returns 1 for success and 0 or -1 for failure.
|
||||
|
||||
BIO_eof() returns 1 if EOF has been reached 0 otherwise.
|
||||
|
||||
BIO_set_close() always returns 1.
|
||||
|
||||
BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
|
||||
|
||||
BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
|
||||
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_ex().
|
||||
The BIO_should_retry() call should be used and appropriate action taken
|
||||
is the call fails.
|
||||
|
||||
The return values of BIO_pending() and BIO_wpending() may not reliably
|
||||
determine the amount of pending data in all cases. For example in the
|
||||
case of a file BIO some data may be available in the FILE structures
|
||||
internal buffers but it is not possible to determine this in a
|
||||
portably way. For other types of BIO they may not be supported.
|
||||
|
||||
Filter BIOs if they do not internally handle a particular BIO_ctrl()
|
||||
operation usually pass the operation to the next BIO in the chain.
|
||||
This often means there is no need to locate the required BIO for
|
||||
a particular operation, it can be called on a chain and it will
|
||||
be automatically passed to the relevant BIO. However, this can cause
|
||||
unexpected results: for example no current filter BIOs implement
|
||||
BIO_seek(), but this may still succeed if the chain ends in a FILE
|
||||
or file descriptor BIO.
|
||||
|
||||
Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl()
|
||||
operation.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
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.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,91 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_f_base64 - base64 BIO filter
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment multiple includes
|
||||
|
||||
#include <openssl/bio.h>
|
||||
#include <openssl/evp.h>
|
||||
|
||||
const BIO_METHOD *BIO_f_base64(void);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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().
|
||||
|
||||
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
|
||||
to flush the final block through the BIO.
|
||||
|
||||
The flag BIO_FLAGS_BASE64_NO_NL can be set with BIO_set_flags()
|
||||
to encode the data all on one line or expect the data to be all
|
||||
on one line.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Because of the format of base64 encoding the end of the encoded
|
||||
block cannot always be reliably determined.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_f_base64() returns the base64 BIO method.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Base64 encode the string "Hello World\n" and write the result
|
||||
to standard output:
|
||||
|
||||
BIO *bio, *b64;
|
||||
char message[] = "Hello World \n";
|
||||
|
||||
b64 = BIO_new(BIO_f_base64());
|
||||
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
|
||||
BIO_push(b64, bio);
|
||||
BIO_write(b64, message, strlen(message));
|
||||
BIO_flush(b64);
|
||||
|
||||
BIO_free_all(b64);
|
||||
|
||||
Read Base64 encoded data from standard input and write the decoded
|
||||
data to standard output:
|
||||
|
||||
BIO *bio, *b64, *bio_out;
|
||||
char inbuf[512];
|
||||
int inlen;
|
||||
|
||||
b64 = BIO_new(BIO_f_base64());
|
||||
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);
|
||||
|
||||
BIO_flush(bio_out);
|
||||
BIO_free_all(b64);
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The ambiguity of EOF in base64 encoded data can cause additional
|
||||
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 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
|
||||
@@ -0,0 +1,102 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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>
|
||||
|
||||
const BIO_METHOD *BIO_f_buffer(void);
|
||||
|
||||
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
|
||||
|
||||
BIO_f_buffer() returns the buffering BIO method.
|
||||
|
||||
Data written to a buffering BIO is buffered and periodically written
|
||||
to the next BIO in the chain. Data read from a buffering BIO comes from
|
||||
an internal buffer which is filled from the next BIO in the chain.
|
||||
Both BIO_gets() and BIO_puts() are supported.
|
||||
|
||||
Calling BIO_reset() on a buffering BIO clears any buffered data.
|
||||
|
||||
BIO_get_buffer_num_lines() returns the number of lines currently buffered.
|
||||
|
||||
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
|
||||
set the read, write or both read and write buffer sizes to B<size>. The initial
|
||||
buffer size is DEFAULT_BUFFER_SIZE, currently 4096. Any attempt to reduce the
|
||||
buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared
|
||||
when the buffer is resized.
|
||||
|
||||
BIO_set_buffer_read_data() clears the read buffer and fills it with B<num>
|
||||
bytes of B<buf>. If B<num> is larger than the current buffer size the buffer
|
||||
is expanded.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
These functions, other than BIO_f_buffer(), are implemented as macros.
|
||||
|
||||
Buffering BIOs implement BIO_read_ex() and BIO_gets() by using
|
||||
BIO_read_ex() operations on the next BIO in the chain and storing the
|
||||
result in an internal buffer, from which bytes are given back to the
|
||||
caller as appropriate for the call; a BIO_gets() is guaranteed to give
|
||||
the caller a whole line, and BIO_read_ex() is guaranteed to give the
|
||||
caller the number of bytes it asks for, unless there's an error or end
|
||||
of communication is reached in the next BIO. By prepending a
|
||||
buffering BIO to a chain it is therefore possible to provide
|
||||
BIO_gets() or exact size BIO_read_ex() functionality if the following
|
||||
BIOs do not support it.
|
||||
|
||||
Do not add more than one BIO_f_buffer() to a BIO chain. The result of
|
||||
doing so will force a full read of the size of the internal buffer of
|
||||
the top BIO_f_buffer(), which is 4 KiB at a minimum.
|
||||
|
||||
Data is only written to the next BIO in the chain when the write buffer fills
|
||||
or when BIO_flush() is called. It is therefore important to call BIO_flush()
|
||||
whenever any pending data should be written such as when removing a buffering
|
||||
BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate
|
||||
source/sink BIO is non blocking.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_f_buffer() returns the buffering BIO method.
|
||||
|
||||
BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0).
|
||||
|
||||
BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size()
|
||||
return 1 if the buffer was successfully resized or 0 for failure.
|
||||
|
||||
BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if
|
||||
there was an error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<bio(7)>,
|
||||
L<BIO_reset(3)>,
|
||||
L<BIO_flush(3)>,
|
||||
L<BIO_pop(3)>,
|
||||
L<BIO_ctrl(3)>.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,81 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment multiple includes
|
||||
|
||||
#include <openssl/bio.h>
|
||||
#include <openssl/evp.h>
|
||||
|
||||
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)
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_f_cipher() returns the cipher BIO method. This is a filter
|
||||
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().
|
||||
|
||||
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
|
||||
to flush and possibly pad the final block through the BIO.
|
||||
|
||||
BIO_set_cipher() sets the cipher of BIO B<b> to B<cipher> using key B<key>
|
||||
and IV B<iv>. B<enc> should be set to 1 for encryption and zero for
|
||||
decryption.
|
||||
|
||||
When reading from an encryption BIO the final block is automatically
|
||||
decrypted and checked when EOF is detected. BIO_get_cipher_status()
|
||||
is a BIO_ctrl() macro which can be called to determine whether the
|
||||
decryption operation was successful.
|
||||
|
||||
BIO_get_cipher_ctx() is a BIO_ctrl() macro which retrieves the internal
|
||||
BIO cipher context. The retrieved context can be used in conjunction
|
||||
with the standard cipher routines to set it up. This is useful when
|
||||
BIO_set_cipher() is not flexible enough for the applications needs.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
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 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.
|
||||
|
||||
As always, if BIO_gets() or BIO_puts() support is needed then it can
|
||||
be achieved by preceding the cipher BIO with a buffering BIO.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_f_cipher() returns the cipher BIO method.
|
||||
|
||||
BIO_set_cipher() does not return a value.
|
||||
|
||||
BIO_get_cipher_status() returns 1 for a successful decrypt and 0
|
||||
for failure.
|
||||
|
||||
BIO_get_cipher_ctx() currently always returns 1.
|
||||
|
||||
=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
|
||||
@@ -0,0 +1,162 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment multiple includes
|
||||
|
||||
#include <openssl/bio.h>
|
||||
#include <openssl/evp.h>
|
||||
|
||||
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
|
||||
|
||||
BIO_f_md() returns the message digest BIO method. This is a filter
|
||||
BIO that digests any data passed through it, it is a BIO wrapper
|
||||
for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
|
||||
and EVP_DigestFinal().
|
||||
|
||||
Any data written or read through a digest BIO using BIO_read_ex() and
|
||||
BIO_write_ex() is digested.
|
||||
|
||||
BIO_gets(), if its B<size> parameter is large enough finishes the
|
||||
digest calculation and returns the digest value. BIO_puts() is
|
||||
not supported.
|
||||
|
||||
BIO_reset() reinitialises a digest BIO.
|
||||
|
||||
BIO_set_md() sets the message digest of BIO B<b> to B<md>: this
|
||||
must be called to initialize a digest BIO before any data is
|
||||
passed through it. It is a BIO_ctrl() macro.
|
||||
|
||||
BIO_get_md() places the a pointer to the digest BIOs digest method
|
||||
in B<mdp>, it is a BIO_ctrl() macro.
|
||||
|
||||
BIO_get_md_ctx() returns the digest BIOs context into B<mdcp>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The context returned by BIO_get_md_ctx() can be used in calls
|
||||
to EVP_DigestFinal() and also the signature routines EVP_SignFinal()
|
||||
and EVP_VerifyFinal().
|
||||
|
||||
The context returned by BIO_get_md_ctx() is an internal context
|
||||
structure. Changes made to this context will affect the digest
|
||||
BIO itself and the context pointer will become invalid when the digest
|
||||
BIO is freed.
|
||||
|
||||
After the digest has been retrieved from a digest BIO it must be
|
||||
reinitialized by calling BIO_reset(), or BIO_set_md() before any more
|
||||
data is passed through it.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
BIO_f_md() returns the digest BIO method.
|
||||
|
||||
BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and
|
||||
0 for failure.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
The following example creates a BIO chain containing an SHA1 and MD5
|
||||
digest BIO and passes the string "Hello World" through it. Error
|
||||
checking has been omitted for clarity.
|
||||
|
||||
BIO *bio, *mdtmp;
|
||||
char message[] = "Hello World";
|
||||
|
||||
bio = BIO_new(BIO_s_null());
|
||||
mdtmp = BIO_new(BIO_f_md());
|
||||
BIO_set_md(mdtmp, EVP_sha1());
|
||||
/*
|
||||
* For BIO_push() we want to append the sink BIO and keep a note of
|
||||
* the start of the chain.
|
||||
*/
|
||||
bio = BIO_push(mdtmp, bio);
|
||||
mdtmp = BIO_new(BIO_f_md());
|
||||
BIO_set_md(mdtmp, EVP_md5());
|
||||
bio = BIO_push(mdtmp, bio);
|
||||
/* Note: mdtmp can now be discarded */
|
||||
BIO_write(bio, message, strlen(message));
|
||||
|
||||
The next example digests data by reading through a chain instead:
|
||||
|
||||
BIO *bio, *mdtmp;
|
||||
char buf[1024];
|
||||
int rdlen;
|
||||
|
||||
bio = BIO_new_file(file, "rb");
|
||||
mdtmp = BIO_new(BIO_f_md());
|
||||
BIO_set_md(mdtmp, EVP_sha1());
|
||||
bio = BIO_push(mdtmp, bio);
|
||||
mdtmp = BIO_new(BIO_f_md());
|
||||
BIO_set_md(mdtmp, EVP_md5());
|
||||
bio = BIO_push(mdtmp, bio);
|
||||
do {
|
||||
rdlen = BIO_read(bio, buf, sizeof(buf));
|
||||
/* Might want to do something with the data here */
|
||||
} 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.
|
||||
|
||||
BIO *mdtmp;
|
||||
unsigned char mdbuf[EVP_MAX_MD_SIZE];
|
||||
int mdlen;
|
||||
int i;
|
||||
|
||||
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);
|
||||
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);
|
||||
|
||||
BIO_free_all(bio);
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The lack of support for BIO_puts() and the non standard behaviour of
|
||||
BIO_gets() could be regarded as anomalous. It could be argued that BIO_gets()
|
||||
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 HISTORY
|
||||
|
||||
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
|
||||
@@ -0,0 +1,39 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_f_null - null filter
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
const BIO_METHOD *BIO_f_null(void);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_f_null() returns the null filter BIO method. This is a filter BIO
|
||||
that does nothing.
|
||||
|
||||
All requests to a null filter BIO are passed through to the next BIO in
|
||||
the chain: this means that a BIO chain containing a null filter BIO
|
||||
behaves just as though the BIO was not there.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
As may be apparent a null filter BIO is not particularly useful.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_f_null() returns the null filter BIO method.
|
||||
|
||||
=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
|
||||
@@ -0,0 +1,308 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment multiple includes
|
||||
|
||||
#include <openssl/bio.h>
|
||||
#include <openssl/ssl.h>
|
||||
|
||||
const BIO_METHOD *BIO_f_ssl(void);
|
||||
|
||||
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_connect(SSL_CTX *ctx);
|
||||
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
|
||||
int BIO_ssl_copy_session_id(BIO *to, BIO *from);
|
||||
void BIO_ssl_shutdown(BIO *bio);
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
then an attempt is made to establish one on the first I/O call.
|
||||
|
||||
If a BIO is appended to an SSL BIO using BIO_push() it is automatically
|
||||
used as the SSL BIOs read and write BIOs.
|
||||
|
||||
Calling BIO_reset() on an SSL BIO closes down any current SSL connection
|
||||
by calling SSL_shutdown(). BIO_reset() is then sent to the next BIO in
|
||||
the chain: this will typically disconnect the underlying transport.
|
||||
The SSL BIO is then reset to the initial accept or connect state.
|
||||
|
||||
If the close flag is set when an SSL BIO is freed then the internal
|
||||
SSL structure is also freed using SSL_free().
|
||||
|
||||
BIO_set_ssl() sets the internal SSL pointer of BIO B<b> to B<ssl> using
|
||||
the close flag B<c>.
|
||||
|
||||
BIO_get_ssl() retrieves the SSL pointer of BIO B<b>, it can then be
|
||||
manipulated using the standard SSL library functions.
|
||||
|
||||
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)
|
||||
the SSL session is automatically renegotiated. B<num> must be at
|
||||
least 512 bytes.
|
||||
|
||||
BIO_set_ssl_renegotiate_timeout() sets the renegotiate timeout to
|
||||
B<seconds>. When the renegotiate timeout elapses the session is
|
||||
automatically renegotiated.
|
||||
|
||||
BIO_get_num_renegotiates() returns the total number of session
|
||||
renegotiations due to I/O or timeout.
|
||||
|
||||
BIO_new_ssl() allocates an SSL BIO using SSL_CTX B<ctx> and using
|
||||
client mode if B<client> is non zero.
|
||||
|
||||
BIO_new_ssl_connect() creates a new BIO chain consisting of an
|
||||
SSL BIO (using B<ctx>) followed by a connect BIO.
|
||||
|
||||
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 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.
|
||||
|
||||
BIO_ssl_shutdown() closes down an SSL connection on BIO
|
||||
chain B<bio>. It does this by locating the SSL BIO in the
|
||||
chain and calling SSL_shutdown() on its internal SSL
|
||||
pointer.
|
||||
|
||||
BIO_do_handshake() attempts to complete an SSL handshake on the
|
||||
supplied BIO and establish the SSL connection. It returns 1
|
||||
if the connection was established successfully. A zero or negative
|
||||
value is returned if the connection could not be established, the
|
||||
call BIO_should_retry() should be used for non blocking connect BIOs
|
||||
to determine if the call should be retried. If an SSL connection has
|
||||
already been established this call has no effect.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
SSL BIOs are exceptional in that if the underlying transport
|
||||
is non blocking they can still request a retry in exceptional
|
||||
circumstances. Specifically this will happen if a session
|
||||
renegotiation takes place during a BIO_read_ex() operation, one
|
||||
case where this happens is when step up occurs.
|
||||
|
||||
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.
|
||||
|
||||
Since unknown BIO_ctrl() operations are sent through filter
|
||||
BIOs the servers name and port can be set using BIO_set_host()
|
||||
on the BIO returned by BIO_new_ssl_connect() without having
|
||||
to locate the connect BIO first.
|
||||
|
||||
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.
|
||||
|
||||
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 RETURN VALUES
|
||||
|
||||
BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
|
||||
|
||||
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
|
||||
BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
|
||||
success or a value which is less than or equal to 0 if an error occurred.
|
||||
|
||||
BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
|
||||
a valid B<BIO> structure on success or B<NULL> if an error occurred.
|
||||
|
||||
BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
|
||||
|
||||
BIO_do_handshake() returns 1 if the connection was established successfully.
|
||||
A zero or negative value is returned if the connection could not be established.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
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 *sbio, *out;
|
||||
int len;
|
||||
char tmpbuf[1024];
|
||||
SSL_CTX *ctx;
|
||||
SSL *ssl;
|
||||
|
||||
/* XXX Seed the PRNG if needed. */
|
||||
|
||||
ctx = SSL_CTX_new(TLS_client_method());
|
||||
|
||||
/* XXX Set verify paths and mode here. */
|
||||
|
||||
sbio = BIO_new_ssl_connect(ctx);
|
||||
BIO_get_ssl(sbio, &ssl);
|
||||
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);
|
||||
|
||||
/* XXX We might want to do other things with ssl here */
|
||||
|
||||
/* 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);
|
||||
exit(1);
|
||||
}
|
||||
if (BIO_do_handshake(sbio) <= 0) {
|
||||
fprintf(stderr, "Error establishing SSL connection\n");
|
||||
ERR_print_errors_fp(stderr);
|
||||
exit(1);
|
||||
}
|
||||
|
||||
/* 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);
|
||||
}
|
||||
BIO_free_all(sbio);
|
||||
BIO_free(out);
|
||||
|
||||
Here is a simple server example. It makes use of a buffering
|
||||
BIO to allow lines to be read from the SSL BIO using BIO_gets.
|
||||
It creates a pseudo web page containing the actual request from
|
||||
a client and also echoes the request to standard output.
|
||||
|
||||
BIO *sbio, *bbio, *acpt, *out;
|
||||
int len;
|
||||
char tmpbuf[1024];
|
||||
SSL_CTX *ctx;
|
||||
SSL *ssl;
|
||||
|
||||
/* XXX Seed the PRNG if needed. */
|
||||
|
||||
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);
|
||||
}
|
||||
|
||||
/* XXX Other things like set verify locations, EDH temp callbacks. */
|
||||
|
||||
/* New SSL BIO setup as server */
|
||||
sbio = BIO_new_ssl(ctx, 0);
|
||||
BIO_get_ssl(sbio, &ssl);
|
||||
if (ssl == NULL) {
|
||||
fprintf(stderr, "Can't locate SSL pointer\n");
|
||||
ERR_print_errors_fp(stderr);
|
||||
exit(1);
|
||||
}
|
||||
|
||||
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
|
||||
bbio = BIO_new(BIO_f_buffer());
|
||||
sbio = BIO_push(bbio, sbio);
|
||||
acpt = BIO_new_accept("4433");
|
||||
|
||||
/*
|
||||
* 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.
|
||||
*/
|
||||
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);
|
||||
exit(1);
|
||||
}
|
||||
|
||||
/* 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);
|
||||
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;
|
||||
}
|
||||
|
||||
BIO_puts(sbio, "--------------------------------------------------\r\n");
|
||||
BIO_puts(sbio, "\r\n");
|
||||
BIO_flush(sbio);
|
||||
BIO_free_all(sbio);
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
|
||||
the I/O BIO reference count was incorrectly incremented (instead of
|
||||
decremented) and dissociated with the SSL BIO even if the SSL BIO was not
|
||||
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 COPYRIGHT
|
||||
|
||||
Copyright 2000-2019 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
|
||||
@@ -0,0 +1,70 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
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 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.
|
||||
|
||||
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
|
||||
certain type.
|
||||
|
||||
BIO_method_type() returns the type of a BIO.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_find_type() returns a matching BIO or NULL for no match.
|
||||
|
||||
BIO_next() returns the next BIO in a chain.
|
||||
|
||||
BIO_method_type() returns the type of the BIO B<b>.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Traverse a chain looking for digest BIOs:
|
||||
|
||||
BIO *btmp;
|
||||
|
||||
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_next(btmp);
|
||||
} while (btmp);
|
||||
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2019 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
|
||||
@@ -0,0 +1,65 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown,
|
||||
BIO_get_shutdown - functions for managing BIO state information
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
void BIO_set_data(BIO *a, void *ptr);
|
||||
void *BIO_get_data(BIO *a);
|
||||
void BIO_set_init(BIO *a, int init);
|
||||
int BIO_get_init(BIO *a);
|
||||
void BIO_set_shutdown(BIO *a, int shut);
|
||||
int BIO_get_shutdown(BIO *a);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
These functions are mainly useful when implementing a custom BIO.
|
||||
|
||||
The BIO_set_data() function associates the custom data pointed to by B<ptr> with
|
||||
the BIO. This data can subsequently be retrieved via a call to BIO_get_data().
|
||||
This can be used by custom BIOs for storing implementation specific information.
|
||||
|
||||
The BIO_set_init() function sets the value of the BIO's "init" flag to indicate
|
||||
whether initialisation has been completed for this BIO or not. A nonzero value
|
||||
indicates that initialisation is complete, whilst zero indicates that it is not.
|
||||
Often initialisation will complete during initial construction of the BIO. For
|
||||
some BIOs however, initialisation may not complete until after additional steps
|
||||
have occurred (for example through calling custom ctrls). The BIO_get_init()
|
||||
function returns the value of the "init" flag.
|
||||
|
||||
The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of
|
||||
this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource
|
||||
is also closed when the BIO is freed.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_get_data() returns a pointer to the implementation specific custom data
|
||||
associated with this BIO, or NULL if none has been set.
|
||||
|
||||
BIO_get_init() returns the state of the BIO's init flag.
|
||||
|
||||
BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<bio>, L<BIO_meth_new>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The functions described here were added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2020 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
|
||||
@@ -0,0 +1,72 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data,
|
||||
ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
|
||||
UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data,
|
||||
X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data,
|
||||
X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data,
|
||||
X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data,
|
||||
DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
|
||||
DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
|
||||
ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data,
|
||||
EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data,
|
||||
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
|
||||
- application-specific data
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=for comment generic
|
||||
|
||||
#include <openssl/x509.h>
|
||||
|
||||
int TYPE_get_ex_new_index(long argl, void *argp,
|
||||
CRYPTO_EX_new *new_func,
|
||||
CRYPTO_EX_dup *dup_func,
|
||||
CRYPTO_EX_free *free_func);
|
||||
|
||||
int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
|
||||
|
||||
void *TYPE_get_ex_data(TYPE *d, int idx);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
In the description here, I<TYPE> is used a placeholder
|
||||
for any of the OpenSSL datatypes listed in
|
||||
L<CRYPTO_get_ex_new_index(3)>.
|
||||
|
||||
These functions handle application-specific data for OpenSSL data
|
||||
structures.
|
||||
|
||||
TYPE_get_ex_new_index() is a macro that calls CRYPTO_get_ex_new_index()
|
||||
with the correct B<index> value.
|
||||
|
||||
TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
|
||||
an offset into the opaque exdata part of the TYPE object.
|
||||
|
||||
TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with
|
||||
an offset into the opaque exdata part of the TYPE object.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
TYPE_get_ex_new_index() returns a new index on success or -1 on error.
|
||||
|
||||
TYPE_set_ex_data() returns 1 on success or 0 on error.
|
||||
|
||||
TYPE_get_ex_data() returns the application data or NULL if an error occurred.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<CRYPTO_get_ex_new_index(3)>.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2015-2020 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
|
||||
@@ -0,0 +1,164 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_get_new_index,
|
||||
BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex,
|
||||
BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write,
|
||||
BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts,
|
||||
BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl,
|
||||
BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create,
|
||||
BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
|
||||
BIO_meth_set_callback_ctrl - Routines to build up BIO methods
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
int BIO_get_new_index(void);
|
||||
|
||||
BIO_METHOD *BIO_meth_new(int type, const char *name);
|
||||
|
||||
void BIO_meth_free(BIO_METHOD *biom);
|
||||
|
||||
int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,
|
||||
size_t *);
|
||||
int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);
|
||||
int BIO_meth_set_write_ex(BIO_METHOD *biom,
|
||||
int (*bwrite)(BIO *, const char *, size_t, size_t *));
|
||||
int BIO_meth_set_write(BIO_METHOD *biom,
|
||||
int (*write)(BIO *, const char *, int));
|
||||
|
||||
int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);
|
||||
int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);
|
||||
int BIO_meth_set_read_ex(BIO_METHOD *biom,
|
||||
int (*bread)(BIO *, char *, size_t, size_t *));
|
||||
int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));
|
||||
|
||||
int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);
|
||||
int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));
|
||||
|
||||
int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);
|
||||
int BIO_meth_set_gets(BIO_METHOD *biom,
|
||||
int (*gets)(BIO *, char *, int));
|
||||
|
||||
long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);
|
||||
int BIO_meth_set_ctrl(BIO_METHOD *biom,
|
||||
long (*ctrl)(BIO *, int, long, void *));
|
||||
|
||||
int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);
|
||||
int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));
|
||||
|
||||
int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);
|
||||
int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));
|
||||
|
||||
long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);
|
||||
int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
|
||||
long (*callback_ctrl)(BIO *, int, BIO_info_cb *));
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<BIO_METHOD> type is a structure used for the implementation of new BIO
|
||||
types. It provides a set of functions used by OpenSSL for the implementation
|
||||
of the various BIO capabilities. See the L<bio> page for more information.
|
||||
|
||||
BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
|
||||
unique integer B<type> and a string that represents its B<name>.
|
||||
Use BIO_get_new_index() to get the value for B<type>.
|
||||
|
||||
The set of
|
||||
standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
|
||||
include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
|
||||
type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
|
||||
should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
|
||||
based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
|
||||
"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
|
||||
more information.
|
||||
|
||||
BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
|
||||
associated with it.
|
||||
|
||||
BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function
|
||||
used for writing arbitrary length data to the BIO respectively. This function
|
||||
will be called in response to the application calling BIO_write_ex() or
|
||||
BIO_write(). The parameters for the function have the same meaning as for
|
||||
BIO_write_ex(). Older code may call BIO_meth_get_write() and
|
||||
BIO_meth_set_write() instead. Applications should not call both
|
||||
BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write()
|
||||
when the function was set with BIO_meth_set_write_ex().
|
||||
|
||||
BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used
|
||||
for reading arbitrary length data from the BIO respectively. This function will
|
||||
be called in response to the application calling BIO_read_ex() or BIO_read().
|
||||
The parameters for the function have the same meaning as for BIO_read_ex().
|
||||
Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.
|
||||
Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read()
|
||||
or call BIO_meth_get_read() when the function was set with
|
||||
BIO_meth_set_read_ex().
|
||||
|
||||
BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
|
||||
writing a NULL terminated string to the BIO respectively. This function will be
|
||||
called in response to the application calling BIO_puts(). The parameters for
|
||||
the function have the same meaning as for BIO_puts().
|
||||
|
||||
BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
|
||||
used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
|
||||
page for more information). This function will be called in response to the
|
||||
application calling BIO_gets(). The parameters for the function have the same
|
||||
meaning as for BIO_gets().
|
||||
|
||||
BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
|
||||
processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
|
||||
more information. This function will be called in response to the application
|
||||
calling BIO_ctrl(). The parameters for the function have the same meaning as for
|
||||
BIO_ctrl().
|
||||
|
||||
BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
|
||||
for creating a new instance of the BIO respectively. This function will be
|
||||
called in response to the application calling BIO_new() and passing
|
||||
in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
|
||||
memory for the new BIO, and a pointer to this newly allocated structure will
|
||||
be passed as a parameter to the function.
|
||||
|
||||
BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
|
||||
for destroying an instance of a BIO respectively. This function will be
|
||||
called in response to the application calling BIO_free(). A pointer to the BIO
|
||||
to be destroyed is passed as a parameter. The destroy function should be used
|
||||
for BIO specific clean up. The memory for the BIO itself should not be freed by
|
||||
this function.
|
||||
|
||||
BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
|
||||
function used for processing callback ctrl messages in the BIO respectively. See
|
||||
the L<BIO_callback_ctrl(3)> page for more information. This function will be called
|
||||
in response to the application calling BIO_callback_ctrl(). The parameters for
|
||||
the function have the same meaning as for BIO_callback_ctrl().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.
|
||||
|
||||
BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL
|
||||
if an error occurred.
|
||||
|
||||
The B<BIO_meth_set> functions return 1 on success or 0 on error.
|
||||
|
||||
The B<BIO_meth_get> functions return the corresponding function pointers.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read_ex>, L<BIO_new>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The functions described here were added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2018 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
|
||||
@@ -0,0 +1,71 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all
|
||||
- BIO allocation and freeing functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
BIO * BIO_new(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_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.
|
||||
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_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
|
||||
|
||||
If BIO_free() is called on a BIO chain it will only free one BIO resulting
|
||||
in a memory leak.
|
||||
|
||||
Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free()
|
||||
on it other than the discarded return value.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Create a memory BIO:
|
||||
|
||||
BIO *mem = BIO_new(BIO_s_mem());
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2019 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
|
||||
@@ -0,0 +1,75 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_new_CMS - CMS streaming filter BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/cms.h>
|
||||
|
||||
BIO *BIO_new_CMS(BIO *out, CMS_ContentInfo *cms);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_new_CMS() returns a streaming filter BIO chain based on B<cms>. The output
|
||||
of the filter is written to B<out>. Any data written to the chain is
|
||||
automatically translated to a BER format CMS structure of the appropriate type.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The chain returned by this function behaves like a standard filter BIO. It
|
||||
supports non blocking I/O. Content is processed and streamed on the fly and not
|
||||
all held in memory at once: so it is possible to encode very large structures.
|
||||
After all content has been written through the chain BIO_flush() must be called
|
||||
to finalise the structure.
|
||||
|
||||
The B<CMS_STREAM> flag must be included in the corresponding B<flags>
|
||||
parameter of the B<cms> creation function.
|
||||
|
||||
If an application wishes to write additional data to B<out> BIOs should be
|
||||
removed from the chain using BIO_pop() and freed with BIO_free() until B<out>
|
||||
is reached. If no additional data needs to be written BIO_free_all() can be
|
||||
called to free up the whole chain.
|
||||
|
||||
Any content written through the filter is used verbatim: no canonical
|
||||
translation is performed.
|
||||
|
||||
It is possible to chain multiple BIOs to, for example, create a triple wrapped
|
||||
signed, enveloped, signed structure. In this case it is the applications
|
||||
responsibility to set the inner content type of any outer CMS_ContentInfo
|
||||
structures.
|
||||
|
||||
Large numbers of small writes through the chain should be avoided as this will
|
||||
produce an output consisting of lots of OCTET STRING structures. Prepending
|
||||
a BIO_f_buffer() buffering BIO will prevent this.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
There is currently no corresponding inverse BIO: i.e. one which can decode
|
||||
a CMS structure on the fly.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_new_CMS() returns a BIO chain when successful or NULL if an error
|
||||
occurred. The error can be obtained from ERR_get_error(3).
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ERR_get_error(3)>, L<CMS_sign(3)>,
|
||||
L<CMS_encrypt(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The BIO_new_CMS() function 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
|
||||
@@ -0,0 +1,78 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_hostserv_priorities,
|
||||
BIO_parse_hostserv
|
||||
- utility routines to parse a standard host and service string
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
enum BIO_hostserv_priorities {
|
||||
BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
|
||||
};
|
||||
int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
|
||||
enum BIO_hostserv_priorities hostserv_prio);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_parse_hostserv() will parse the information given in B<hostserv>,
|
||||
create strings with the hostname and service name and give those
|
||||
back via B<host> and B<service>. Those will need to be freed after
|
||||
they are used. B<hostserv_prio> helps determine if B<hostserv> shall
|
||||
be interpreted primarily as a hostname or a service name in ambiguous
|
||||
cases.
|
||||
|
||||
The syntax the BIO_parse_hostserv() recognises is:
|
||||
|
||||
host + ':' + service
|
||||
host + ':' + '*'
|
||||
host + ':'
|
||||
':' + service
|
||||
'*' + ':' + service
|
||||
host
|
||||
service
|
||||
|
||||
The host part can be a name or an IP address. If it's a IPv6
|
||||
address, it MUST be enclosed in brackets, such as '[::1]'.
|
||||
|
||||
The service part can be a service name or its port number.
|
||||
|
||||
The returned values will depend on the given B<hostserv> string
|
||||
and B<hostserv_prio>, as follows:
|
||||
|
||||
host + ':' + service => *host = "host", *service = "service"
|
||||
host + ':' + '*' => *host = "host", *service = NULL
|
||||
host + ':' => *host = "host", *service = NULL
|
||||
':' + service => *host = NULL, *service = "service"
|
||||
'*' + ':' + service => *host = NULL, *service = "service"
|
||||
|
||||
in case no ':' is present in the string, the result depends on
|
||||
hostserv_prio, as follows:
|
||||
|
||||
when hostserv_prio == BIO_PARSE_PRIO_HOST
|
||||
host => *host = "host", *service untouched
|
||||
|
||||
when hostserv_prio == BIO_PARSE_PRIO_SERV
|
||||
service => *host untouched, *service = "service"
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_parse_hostserv() returns 1 on success or 0 on error.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_ADDRINFO(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2016-2020 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
|
||||
@@ -0,0 +1,50 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf
|
||||
- formatted output to a BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
int BIO_printf(BIO *bio, const char *format, ...)
|
||||
int BIO_vprintf(BIO *bio, const char *format, va_list args)
|
||||
|
||||
int BIO_snprintf(char *buf, size_t n, const char *format, ...)
|
||||
int BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args)
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_printf() is similar to the standard C printf() function, except that
|
||||
the output is sent to the specified BIO, B<bio>, rather than standard
|
||||
output. All common format specifiers are supported.
|
||||
|
||||
BIO_vprintf() is similar to the vprintf() function found on many platforms,
|
||||
the output is sent to the specified BIO, B<bio>, rather than standard
|
||||
output. All common format specifiers are supported. The argument
|
||||
list B<args> is a stdarg argument list.
|
||||
|
||||
BIO_snprintf() is for platforms that do not have the common snprintf()
|
||||
function. It is like sprintf() except that the size parameter, B<n>,
|
||||
specifies the size of the output buffer.
|
||||
|
||||
BIO_vsnprintf() is to BIO_snprintf() as BIO_vprintf() is to BIO_printf().
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
All functions return the number of bytes written, or -1 on error.
|
||||
For BIO_snprintf() and BIO_vsnprintf() this includes when the output
|
||||
buffer is too small.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2017 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
|
||||
@@ -0,0 +1,89 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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);
|
||||
void BIO_set_next(BIO *b, BIO *next);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The BIO_push() function appends the BIO B<append> to B<b>, it returns
|
||||
B<b>.
|
||||
|
||||
BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
|
||||
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()
|
||||
joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
|
||||
the deleted BIO does not need to be at the end of a chain.
|
||||
|
||||
The process of calling BIO_push() and BIO_pop() on a BIO may have additional
|
||||
consequences (a control call is made to the affected BIOs) any effects will
|
||||
be noted in the descriptions of individual BIOs.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_push() returns the end of the chain, B<b>.
|
||||
|
||||
BIO_pop() returns the next BIO in the chain, or NULL if there is no next
|
||||
BIO.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
|
||||
a base64 BIO and B<f> is a file BIO.
|
||||
|
||||
If the call:
|
||||
|
||||
BIO_push(b64, f);
|
||||
|
||||
is made then the new chain will be B<b64-f>. After making the calls
|
||||
|
||||
BIO_push(md2, b64);
|
||||
BIO_push(md1, md2);
|
||||
|
||||
the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
|
||||
by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
|
||||
|
||||
It should be noted that reading causes data to pass in the reverse
|
||||
direction, that is data is read from B<f>, base64 B<decoded> and digested
|
||||
by B<md1> and B<md2>. If the call:
|
||||
|
||||
BIO_pop(md2);
|
||||
|
||||
The call will return B<b64> and the new chain will be B<md1-b64-f> data can
|
||||
be written to B<md1> as before.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<bio>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The BIO_set_next() function was added in OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2019 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
|
||||
@@ -0,0 +1,97 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_puts
|
||||
- BIO I/O functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
int BIO_read_ex(BIO *b, void *data, size_t dlen, size_t *readbytes);
|
||||
int BIO_write_ex(BIO *b, const void *data, size_t dlen, size_t *written);
|
||||
|
||||
int BIO_read(BIO *b, void *data, int dlen);
|
||||
int BIO_gets(BIO *b, char *buf, int size);
|
||||
int BIO_write(BIO *b, const void *data, int dlen);
|
||||
int BIO_puts(BIO *b, const char *buf);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_read_ex() attempts to read B<dlen> bytes from BIO B<b> and places the data
|
||||
in B<data>. If any bytes were successfully read then the number of bytes read is
|
||||
stored in B<*readbytes>.
|
||||
|
||||
BIO_write_ex() attempts to write B<dlen> bytes from B<data> to BIO B<b>. If
|
||||
successful then the number of bytes written is stored in B<*written>.
|
||||
|
||||
BIO_read() attempts to read B<len> bytes from BIO B<b> and places
|
||||
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<size-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 and the '\n' is preserved
|
||||
if present in the input data.
|
||||
|
||||
BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
|
||||
|
||||
BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_read_ex() and BIO_write_ex() return 1 if data was successfully read or
|
||||
written, and 0 otherwise.
|
||||
|
||||
All other 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 trailing
|
||||
NUL is not included in the length returned by BIO_gets().
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A 0 or -1 return is not necessarily an indication of an error. In
|
||||
particular when the source/sink is nonblocking or of a certain type
|
||||
it may merely be an indication that no data is currently available and that
|
||||
the application should retry the operation later.
|
||||
|
||||
One technique sometimes used with blocking sockets is to use a system call
|
||||
(such as select(), poll() or equivalent) to determine when data is available
|
||||
and then call read() to read the data. The equivalent with BIOs (that is call
|
||||
select() on the underlying I/O structure and then call BIO_read() to
|
||||
read the data) should B<not> be used because a single call to BIO_read()
|
||||
can cause several reads (and writes in the case of SSL BIOs) on the underlying
|
||||
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)> 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)>
|
||||
to the chain.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_should_retry(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
BIO_gets() on 1.1.0 and older when called on BIO_fd() based BIO does not
|
||||
keep the '\n' at the end of the line in the buffer.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,234 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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_get_peer_name, BIO_get_peer_port,
|
||||
BIO_get_accept_ip_family, BIO_set_accept_ip_family,
|
||||
BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
const BIO_METHOD *BIO_s_accept(void);
|
||||
|
||||
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);
|
||||
|
||||
long BIO_set_nbio_accept(BIO *b, int n);
|
||||
long BIO_set_accept_bios(BIO *b, char *bio);
|
||||
|
||||
char *BIO_get_peer_name(BIO *b);
|
||||
char *BIO_get_peer_port(BIO *b);
|
||||
long BIO_get_accept_ip_family(BIO *b);
|
||||
long BIO_set_accept_ip_family(BIO *b, long family);
|
||||
|
||||
long BIO_set_bind_mode(BIO *b, long mode);
|
||||
long BIO_get_bind_mode(BIO *b);
|
||||
|
||||
int BIO_do_accept(BIO *b);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_s_accept() returns the accept BIO method. This is a wrapper
|
||||
round the platform's TCP/IP socket accept routines.
|
||||
|
||||
Using accept BIOs, TCP/IP connections can be accepted and data
|
||||
transferred using only BIO routines. In this way any platform
|
||||
specific operations are hidden by the BIO abstraction.
|
||||
|
||||
Read and write operations on an accept BIO will perform I/O
|
||||
on the underlying connection. If no connection is established
|
||||
and the port (see below) is set up properly then the BIO
|
||||
waits for an incoming connection.
|
||||
|
||||
Accept BIOs support BIO_puts() but not BIO_gets().
|
||||
|
||||
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 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_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 "*" 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_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>.
|
||||
|
||||
BIO_set_nbio_accept() sets the accept socket to blocking mode
|
||||
(the default) if B<n> is 0 or non blocking mode if B<n> is 1.
|
||||
|
||||
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
|
||||
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 B<BIO_BIND_NORMAL> (the default) is set
|
||||
then another socket cannot be bound to the same port. If
|
||||
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 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
|
||||
to create the accept socket and bind an address to it. Second
|
||||
and subsequent calls to BIO_do_accept() will await an incoming
|
||||
connection, or request a retry in non blocking mode.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
When an accept BIO is at the end of a chain it will await an
|
||||
incoming connection before processing I/O calls. When an accept
|
||||
BIO is not at then end of a chain it passes I/O calls to the next
|
||||
BIO in the chain.
|
||||
|
||||
When a connection is established a new socket BIO is created for
|
||||
the connection and appended to the chain. That is the chain is now
|
||||
accept->socket. This effectively means that attempting I/O on
|
||||
an initial accept socket will await an incoming connection then
|
||||
perform I/O on it.
|
||||
|
||||
If any additional BIOs have been set using BIO_set_accept_bios()
|
||||
then they are placed between the socket and the accept BIO,
|
||||
that is the chain will be accept->otherbios->socket.
|
||||
|
||||
If a server wishes to process multiple connections (as is normally
|
||||
the case) then the accept BIO must be made available for further
|
||||
incoming connections. This can be done by waiting for a connection and
|
||||
then calling:
|
||||
|
||||
connection = BIO_pop(accept);
|
||||
|
||||
After this call B<connection> will contain a BIO for the recently
|
||||
established connection and B<accept> will now be a single BIO
|
||||
again which can be used to await further incoming connections.
|
||||
If no further connections will be accepted the B<accept> can
|
||||
be freed using BIO_free().
|
||||
|
||||
If only a single connection will be processed it is possible to
|
||||
perform I/O using the accept BIO itself. This is often undesirable
|
||||
however because the accept BIO will still accept additional incoming
|
||||
connections. This can be resolved by using BIO_pop() (see above)
|
||||
and freeing up the accept BIO after the initial connection.
|
||||
|
||||
If the underlying accept socket is nonblocking and BIO_do_accept() is
|
||||
called to await an incoming connection it is possible for
|
||||
BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
|
||||
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_name(), BIO_get_accept_name(), BIO_set_accept_port(),
|
||||
BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
|
||||
BIO_get_peer_name(), BIO_get_peer_port(),
|
||||
BIO_get_accept_ip_family(), BIO_set_accept_ip_family(),
|
||||
BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_do_accept(),
|
||||
BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
|
||||
BIO_set_accept_bios(), BIO_set_accept_ip_family(), 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_peer_name() returns the peer name or NULL on error.
|
||||
|
||||
BIO_get_accept_port() returns the accept port as a string or NULL on error.
|
||||
BIO_get_peer_port() returns the peer port as a string or NULL on error.
|
||||
BIO_get_accept_ip_family() returns the IP family or -1 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 EXAMPLES
|
||||
|
||||
This example accepts two connections on port 4444, sends messages
|
||||
down each and finally closes both down.
|
||||
|
||||
BIO *abio, *cbio, *cbio2;
|
||||
|
||||
/* First call to BIO_accept() sets up accept BIO */
|
||||
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(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(1);
|
||||
}
|
||||
fprintf(stderr, "Connection 2 established\n");
|
||||
|
||||
/* Close accept BIO to refuse further connections */
|
||||
cbio2 = BIO_pop(abio);
|
||||
BIO_free(abio);
|
||||
BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
|
||||
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 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,201 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
const BIO_METHOD *BIO_s_bio(void);
|
||||
|
||||
int BIO_make_bio_pair(BIO *b1, BIO *b2);
|
||||
int BIO_destroy_bio_pair(BIO *b);
|
||||
int BIO_shutdown_wr(BIO *b);
|
||||
|
||||
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);
|
||||
|
||||
int BIO_get_write_guarantee(BIO *b);
|
||||
size_t BIO_ctrl_get_write_guarantee(BIO *b);
|
||||
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
|
||||
|
||||
BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink
|
||||
BIOs where data written to either half of the pair is buffered and can be read from
|
||||
the other half. Both halves must usually by handled by the same application thread
|
||||
since no locking is done on the internal data structures.
|
||||
|
||||
Since BIO chains typically end in a source/sink BIO it is possible to make this
|
||||
one half of a BIO pair and have all the data processed by the chain under application
|
||||
control.
|
||||
|
||||
One typical use of BIO pairs is to place TLS/SSL I/O under application control, this
|
||||
can be used when the application wishes to use a non standard transport for
|
||||
TLS/SSL or the normal socket routines are inappropriate.
|
||||
|
||||
Calls to BIO_read_ex() will read data from the buffer or request a retry if no
|
||||
data is available.
|
||||
|
||||
Calls to BIO_write_ex() will place data in the buffer or request a retry if the
|
||||
buffer is full.
|
||||
|
||||
The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
|
||||
determine the amount of pending data in the read or write buffer.
|
||||
|
||||
BIO_reset() clears any data in the write buffer.
|
||||
|
||||
BIO_make_bio_pair() joins two separate BIOs into a connected pair.
|
||||
|
||||
BIO_destroy_pair() destroys the association between two connected BIOs. Freeing
|
||||
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.
|
||||
|
||||
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
|
||||
17K, sufficient for a maximum size TLS record.
|
||||
|
||||
BIO_get_write_buf_size() returns the size of the write buffer.
|
||||
|
||||
BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
|
||||
BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
|
||||
with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
|
||||
zero then the default size is used. BIO_new_bio_pair() does not check whether
|
||||
B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
|
||||
BIO_free() is not called.
|
||||
|
||||
BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
|
||||
length of data that can be currently written to the BIO. Writes larger than this
|
||||
value will return a value from BIO_write_ex() less than the amount requested or
|
||||
if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a
|
||||
function whereas BIO_get_write_guarantee() is a macro.
|
||||
|
||||
BIO_get_read_request() and BIO_ctrl_get_read_request() return the
|
||||
amount of data requested, or the buffer size if it is less, if the
|
||||
last read attempt at the other half of the BIO pair failed due to an
|
||||
empty buffer. This can be used to determine how much data should be
|
||||
written to the BIO so the next read will succeed: this is most useful
|
||||
in TLS/SSL applications where the amount of data read is usually
|
||||
meaningful rather than just a buffer size. After a successful read
|
||||
this call will return zero. It also will return zero once new data
|
||||
has been written satisfying the read request or part of it.
|
||||
Note that BIO_get_read_request() never returns an amount larger
|
||||
than that returned by BIO_get_write_guarantee().
|
||||
|
||||
BIO_ctrl_reset_read_request() can also be used to reset the value returned by
|
||||
BIO_get_read_request() to zero.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Both halves of a BIO pair should be freed. That is even if one half is implicit
|
||||
freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed.
|
||||
|
||||
When used in bidirectional applications (such as TLS/SSL) care should be taken to
|
||||
flush any data in the write buffer. This can be done by calling BIO_pending()
|
||||
on the other half of the pair and, if any data is pending, reading it and sending
|
||||
it to the underlying transport. This must be done before any normal processing
|
||||
(such as calling select() ) due to a request and BIO_should_read() being true.
|
||||
|
||||
To see why this is important consider a case where a request is sent using
|
||||
BIO_write_ex() and a response read with BIO_read_ex(), this can occur during an
|
||||
TLS/SSL handshake for example. BIO_write_ex() will succeed and place data in the
|
||||
write buffer. BIO_read_ex() will initially fail and BIO_should_read() will be
|
||||
true. If the application then waits for data to be available on the underlying
|
||||
transport before flushing the write buffer it will never succeed because the
|
||||
request was 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
|
||||
B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
|
||||
locations for B<bio1> and B<bio2>. Check the error stack for more information.
|
||||
|
||||
[XXXXX: More return values need to be added here]
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
The BIO pair can be used to have full control over the network access of an
|
||||
application. The application can call select() on the socket as required
|
||||
without having to go through the SSL-interface.
|
||||
|
||||
BIO *internal_bio, *network_bio;
|
||||
|
||||
...
|
||||
BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
|
||||
SSL_set_bio(ssl, internal_bio, internal_bio);
|
||||
SSL_operations(); /* e.g. SSL_read and SSL_write */
|
||||
...
|
||||
|
||||
application | TLS-engine
|
||||
| |
|
||||
+----------> SSL_operations()
|
||||
| /\ ||
|
||||
| || \/
|
||||
| BIO-pair (internal_bio)
|
||||
| BIO-pair (network_bio)
|
||||
| || /\
|
||||
| \/ ||
|
||||
+-----------< BIO_operations()
|
||||
| |
|
||||
| |
|
||||
socket
|
||||
|
||||
...
|
||||
SSL_free(ssl); /* implicitly frees internal_bio */
|
||||
BIO_free(network_bio);
|
||||
...
|
||||
|
||||
As the BIO pair will only buffer the data and never directly access the
|
||||
connection, it behaves nonblocking and will return as soon as the write
|
||||
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 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 WARNINGS
|
||||
|
||||
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
|
||||
the peer might be waiting for the data before being able to continue.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<SSL_set_bio(3)>, L<ssl(7)>, L<bio(7)>,
|
||||
L<BIO_should_retry(3)>, L<BIO_read_ex(3)>
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,213 @@
|
||||
=pod
|
||||
|
||||
=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_family, BIO_get_conn_ip_family,
|
||||
BIO_get_conn_hostname, BIO_get_conn_port,
|
||||
BIO_set_nbio, BIO_do_connect - connect BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
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_address(BIO *b, BIO_ADDR *addr);
|
||||
long BIO_set_conn_ip_family(BIO *b, long family);
|
||||
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);
|
||||
const long BIO_get_conn_ip_family(BIO *b);
|
||||
|
||||
long BIO_set_nbio(BIO *b, long n);
|
||||
|
||||
int BIO_do_connect(BIO *b);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_s_connect() returns the connect BIO method. This is a wrapper
|
||||
round the platform's TCP/IP socket connection routines.
|
||||
|
||||
Using connect BIOs, TCP/IP connections can be made and data
|
||||
transferred using only BIO routines. In this way any platform
|
||||
specific operations are hidden by the BIO abstraction.
|
||||
|
||||
Read and write operations on a connect BIO will perform I/O
|
||||
on the underlying connection. If no connection is established
|
||||
and the port and hostname (see below) is set up properly then
|
||||
a connection is established first.
|
||||
|
||||
Connect BIOs support BIO_puts() but not BIO_gets().
|
||||
|
||||
If the close flag is set on a connect BIO then any active
|
||||
connection is shutdown and the socket closed when the BIO
|
||||
is freed.
|
||||
|
||||
Calling BIO_reset() on a connect BIO will close any active
|
||||
connection and reset the BIO into a state where it can connect
|
||||
to the same host again.
|
||||
|
||||
BIO_get_fd() places the underlying 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_set_conn_hostname() uses the string B<name> to set the hostname.
|
||||
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. This internal
|
||||
list is http, telnet, socks, https, ssl, ftp, and gopher.
|
||||
|
||||
BIO_set_conn_address() sets the address and port information using
|
||||
a BIO_ADDR(3ssl).
|
||||
|
||||
BIO_set_conn_ip_family() sets the IP family.
|
||||
|
||||
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_address() returns the address information as a BIO_ADDR.
|
||||
This return value is an internal pointer which should not be modified.
|
||||
|
||||
BIO_get_conn_ip_family() returns the IP family of the connect BIO.
|
||||
|
||||
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
|
||||
non blocking I/O is set during the connect process.
|
||||
|
||||
BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
|
||||
a single call: that is it creates a new connect BIO with B<name>.
|
||||
|
||||
BIO_do_connect() attempts to connect the supplied BIO. It returns 1
|
||||
if the connection was established successfully. A zero or negative
|
||||
value is returned if the connection could not be established, the
|
||||
call BIO_should_retry() should be used for non blocking connect BIOs
|
||||
to determine if the call should be retried.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
If blocking I/O is set then a non positive return value from any
|
||||
I/O call is caused by an error condition, although a zero return
|
||||
will normally mean that the connection was closed.
|
||||
|
||||
If the port name is supplied as part of the hostname then this will
|
||||
override any value set with BIO_set_conn_port(). This may be undesirable
|
||||
if the application does not wish to allow connection to arbitrary
|
||||
ports. This can be avoided by checking for the presence of the ':'
|
||||
character in the passed hostname and either indicating an error or
|
||||
truncating the string at that point.
|
||||
|
||||
The values returned by BIO_get_conn_hostname(), BIO_get_conn_address(),
|
||||
and BIO_get_conn_port() are updated when a connection attempt is made.
|
||||
Before any connection attempt the values returned are those set by the
|
||||
application itself.
|
||||
|
||||
Applications do not have to call BIO_do_connect() but may wish to do
|
||||
so to separate the connection process from other I/O processing.
|
||||
|
||||
If non blocking I/O is set then retries will be requested as appropriate.
|
||||
|
||||
It addition to BIO_should_read() and BIO_should_write() it is also
|
||||
possible for BIO_should_io_special() to be true during the initial
|
||||
connection process with the reason BIO_RR_CONNECT. If this is returned
|
||||
then this is an indication that a connection attempt would block,
|
||||
the application should then take appropriate action to wait until
|
||||
the underlying socket has connected and retry the call.
|
||||
|
||||
BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_get_conn_hostname(),
|
||||
BIO_set_conn_address(), BIO_get_conn_port(), BIO_get_conn_address(),
|
||||
BIO_set_conn_ip_family(), BIO_get_conn_ip_family(),
|
||||
BIO_set_nbio(), and BIO_do_connect() are macros.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_s_connect() returns the connect BIO method.
|
||||
|
||||
BIO_get_fd() returns the socket or -1 if the BIO has not
|
||||
been initialized.
|
||||
|
||||
BIO_set_conn_address(), BIO_set_conn_port(), and BIO_set_conn_ip_family()
|
||||
always return 1.
|
||||
|
||||
BIO_set_conn_hostname() returns 1 on success and 0 on failure.
|
||||
|
||||
BIO_get_conn_address() returns the address information or NULL if none
|
||||
was set.
|
||||
|
||||
BIO_get_conn_hostname() returns the connected hostname or NULL if
|
||||
none was set.
|
||||
|
||||
BIO_get_conn_ip_family() returns the address family or -1 if none was set.
|
||||
|
||||
BIO_get_conn_port() returns a string representing the connected
|
||||
port or NULL if not set.
|
||||
|
||||
BIO_set_nbio() always returns 1.
|
||||
|
||||
BIO_do_connect() returns 1 if the connection was successfully
|
||||
established and 0 or -1 if the connection failed.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
This is example connects to a webserver on the local host and attempts
|
||||
to retrieve a page and copy the result to standard output.
|
||||
|
||||
|
||||
BIO *cbio, *out;
|
||||
int len;
|
||||
char tmpbuf[1024];
|
||||
|
||||
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);
|
||||
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);
|
||||
}
|
||||
BIO_free(cbio);
|
||||
BIO_free(out);
|
||||
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_ADDR(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(), and BIO_get_conn_ip()
|
||||
were removed in OpenSSL 1.1.0.
|
||||
Use BIO_set_conn_address() and BIO_get_conn_address() instead.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,98 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
const BIO_METHOD *BIO_s_fd(void);
|
||||
|
||||
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);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
|
||||
round the platforms file descriptor routines such as read() and write().
|
||||
|
||||
BIO_read_ex() and BIO_write_ex() read or write the underlying descriptor.
|
||||
BIO_puts() is supported but BIO_gets() is not.
|
||||
|
||||
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
|
||||
such as by using B<lseek(fd, 0, 0)>.
|
||||
|
||||
BIO_seek() sets the file pointer to position B<ofs> from start of file
|
||||
such as by using B<lseek(fd, ofs, 0)>.
|
||||
|
||||
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.
|
||||
|
||||
BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
The behaviour of BIO_read_ex() and BIO_write_ex() depends on the behavior of the
|
||||
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_ex(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_set_fd() always returns 1.
|
||||
|
||||
BIO_get_fd() returns the file descriptor or -1 if the BIO has not
|
||||
been initialized.
|
||||
|
||||
BIO_new_fd() returns the newly allocated BIO or NULL is an error
|
||||
occurred.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
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)>, L<BIO_tell(3)>,
|
||||
L<BIO_reset(3)>, L<BIO_read_ex(3)>,
|
||||
L<BIO_write_ex(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-2019 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
|
||||
@@ -0,0 +1,168 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_s_file, BIO_new_file, BIO_new_fp, BIO_set_fp, BIO_get_fp,
|
||||
BIO_read_filename, BIO_write_filename, BIO_append_filename,
|
||||
BIO_rw_filename - FILE bio
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
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);
|
||||
|
||||
int BIO_read_filename(BIO *b, char *name)
|
||||
int BIO_write_filename(BIO *b, char *name)
|
||||
int BIO_append_filename(BIO *b, char *name)
|
||||
int BIO_rw_filename(BIO *b, char *name)
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_s_file() returns the BIO file method. As its name implies it
|
||||
is a wrapper round the stdio FILE structure and it is a
|
||||
source/sink BIO.
|
||||
|
||||
Calls to BIO_read_ex() and BIO_write_ex() read and write data to the
|
||||
underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
|
||||
|
||||
BIO_flush() on a file BIO calls the fflush() function on the wrapped
|
||||
stream.
|
||||
|
||||
BIO_reset() attempts to change the file pointer to the start of file
|
||||
using fseek(stream, 0, 0).
|
||||
|
||||
BIO_seek() sets the file pointer to position B<ofs> from start of file
|
||||
using fseek(stream, ofs, 0).
|
||||
|
||||
BIO_eof() calls feof().
|
||||
|
||||
Setting the BIO_CLOSE flag calls fclose() on the stream when the BIO
|
||||
is freed.
|
||||
|
||||
BIO_new_file() creates a new file BIO with mode B<mode> the meaning
|
||||
of B<mode> is the same as the stdio function fopen(). The BIO_CLOSE
|
||||
flag is set on the returned BIO.
|
||||
|
||||
BIO_new_fp() creates a file BIO wrapping B<stream>. Flags can be:
|
||||
BIO_CLOSE, BIO_NOCLOSE (the close flag) BIO_FP_TEXT (sets the underlying
|
||||
stream to text mode, default is binary: this only has any effect under
|
||||
Win32).
|
||||
|
||||
BIO_set_fp() sets the fp of a file BIO to B<fp>. B<flags> has the same
|
||||
meaning as in BIO_new_fp(), it is a macro.
|
||||
|
||||
BIO_get_fp() retrieves the fp of a file BIO, it is a macro.
|
||||
|
||||
BIO_seek() is a macro that sets the position pointer to B<offset> bytes
|
||||
from the start of file.
|
||||
|
||||
BIO_tell() returns the value of the position pointer.
|
||||
|
||||
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
|
||||
BIO_rw_filename() set the file BIO B<b> to use file B<name> for
|
||||
reading, writing, append or read write respectively.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
When wrapping stdout, stdin or stderr the underlying stream should not
|
||||
normally be closed so the BIO_NOCLOSE flag should be set.
|
||||
|
||||
Because the file BIO calls the underlying stdio functions any quirks
|
||||
in stdio behaviour will be mirrored by the corresponding BIO.
|
||||
|
||||
On Windows BIO_new_files reserves for the filename argument to be
|
||||
UTF-8 encoded. In other words if you have to make it work in multi-
|
||||
lingual environment, encode filenames in UTF-8.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_s_file() returns the file BIO method.
|
||||
|
||||
BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
|
||||
occurred.
|
||||
|
||||
BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
|
||||
(although the current implementation never return 0).
|
||||
|
||||
BIO_seek() returns the same value as the underlying fseek() function:
|
||||
0 for success or -1 for failure.
|
||||
|
||||
BIO_tell() returns the current file position.
|
||||
|
||||
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
|
||||
BIO_rw_filename() return 1 for success or 0 for failure.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
File BIO "hello world":
|
||||
|
||||
BIO *bio_out;
|
||||
|
||||
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
|
||||
BIO_printf(bio_out, "Hello World\n");
|
||||
|
||||
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 */
|
||||
BIO_printf(bio_out, "Hello World\n");
|
||||
|
||||
Write to a file:
|
||||
|
||||
BIO *out;
|
||||
|
||||
out = BIO_new_file("filename.txt", "w");
|
||||
if (!out)
|
||||
/* Error */
|
||||
BIO_printf(out, "Hello World\n");
|
||||
BIO_free(out);
|
||||
|
||||
Alternative technique:
|
||||
|
||||
BIO *out;
|
||||
|
||||
out = BIO_new(BIO_s_file());
|
||||
if (out == NULL)
|
||||
/* Error */
|
||||
if (!BIO_write_filename(out, "filename.txt"))
|
||||
/* Error */
|
||||
BIO_printf(out, "Hello World\n");
|
||||
BIO_free(out);
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
|
||||
stream. The return value for fseek() is 0 for success or -1 if an error
|
||||
occurred this differs from other types of BIO which will typically return
|
||||
1 for success and a non positive value if an error occurred.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<BIO_seek(3)>, L<BIO_tell(3)>,
|
||||
L<BIO_reset(3)>, L<BIO_flush(3)>,
|
||||
L<BIO_read_ex(3)>,
|
||||
L<BIO_write_ex(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-2020 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
|
||||
@@ -0,0 +1,164 @@
|
||||
=pod
|
||||
|
||||
=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
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
const BIO_METHOD *BIO_s_mem(void);
|
||||
const BIO_METHOD *BIO_s_secmem(void);
|
||||
|
||||
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 *BIO_new_mem_buf(const void *buf, int len);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_s_mem() returns 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.
|
||||
|
||||
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 if the
|
||||
flag BIO_FLAGS_NONCLEAR_RST is not set, otherwise it just restores the read
|
||||
pointer to the state it was just after the last write was performed and the
|
||||
data can be read again. On a read only BIO it similarly restores the BIO to
|
||||
its original state and the read only data can be read again.
|
||||
|
||||
BIO_eof() is true if no data is in the BIO.
|
||||
|
||||
BIO_ctrl_pending() returns the number of bytes currently stored.
|
||||
|
||||
BIO_set_mem_eof_return() sets the behaviour of memory BIO B<b> when it is
|
||||
empty. If the B<v> is zero then an empty memory BIO will return EOF (that is
|
||||
it will return zero and BIO_should_retry(b) will be false. If B<v> is non
|
||||
zero then it will return B<v> when it is empty and it will set the read retry
|
||||
flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
|
||||
positive return value B<v> should be set to a negative value, typically -1.
|
||||
|
||||
BIO_get_mem_data() sets *B<pp> to a pointer to the start of the memory BIOs data
|
||||
and returns the total amount of data available. It is implemented as a macro.
|
||||
|
||||
BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
|
||||
close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
|
||||
It is a macro.
|
||||
|
||||
BIO_get_mem_ptr() places the underlying BUF_MEM structure in *B<pp>. It is
|
||||
a macro.
|
||||
|
||||
BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,
|
||||
if B<len> is -1 then the B<buf> is assumed to be nul terminated and its
|
||||
length is determined by B<strlen>. The BIO is set to a read only state and
|
||||
as a result cannot be written to. This is useful when some data needs to be
|
||||
made available from a static area of memory in the form of a BIO. The
|
||||
supplied data is read directly from the supplied buffer: it is B<not> copied
|
||||
first, so the supplied area of memory must be unchanged until the BIO is freed.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Writes to memory BIOs will always succeed if memory is available: that is
|
||||
their size can grow indefinitely.
|
||||
|
||||
Every write after partial read (not all data in the memory buffer was read)
|
||||
to a read write memory BIO will have to move the unread data with an internal
|
||||
copy operation, if a BIO contains a lot of data and it is read in small
|
||||
chunks intertwined with writes the operation can be very slow. Adding
|
||||
a buffering BIO to the chain can 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.
|
||||
|
||||
Switching the memory BIO from read write to read only is not supported and
|
||||
can give undefined results including a program crash. There are two notable
|
||||
exceptions to the rule. The first one is to assign a static memory buffer
|
||||
immediately after BIO creation and set the BIO as read only.
|
||||
|
||||
The other supported sequence is to start with read write BIO then temporarily
|
||||
switch it to read only and call BIO_reset() on the read only BIO immediately
|
||||
before switching it back to read write. Before the BIO is freed it must be
|
||||
switched back to the read write mode.
|
||||
|
||||
Calling BIO_get_mem_ptr() on read only BIO will return a BUF_MEM that
|
||||
contains only the remaining data to be read. If the close status of the
|
||||
BIO is set to BIO_NOCLOSE, before freeing the BUF_MEM the data pointer
|
||||
in it must be set to NULL as the data pointer does not point to an
|
||||
allocated memory.
|
||||
|
||||
Calling BIO_reset() on a read write memory BIO with BIO_FLAGS_NONCLEAR_RST
|
||||
flag set can have unexpected outcome when the reads and writes to the
|
||||
BIO are intertwined. As documented above the BIO will be reset to the
|
||||
state after the last completed write operation. The effects of reads
|
||||
preceding that write operation cannot be undone.
|
||||
|
||||
Calling BIO_get_mem_ptr() prior to a BIO_reset() call with
|
||||
BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
There should be an option to set the maximum size of a memory BIO.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
|
||||
|
||||
BIO_set_mem_eof_return(), BIO_set_mem_buf() and BIO_get_mem_ptr()
|
||||
return 1 on success or a value which is less than or equal to 0 if an error occurred.
|
||||
|
||||
BIO_get_mem_data() returns the total number of bytes available on success,
|
||||
0 if b is NULL, or a negative value in case of other errors.
|
||||
|
||||
BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
Create a memory BIO and write some data to it:
|
||||
|
||||
BIO *mem = BIO_new(BIO_s_mem());
|
||||
|
||||
BIO_puts(mem, "Hello World\n");
|
||||
|
||||
Create a read only memory BIO:
|
||||
|
||||
char data[] = "Hello World";
|
||||
BIO *mem = BIO_new_mem_buf(data, -1);
|
||||
|
||||
Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
|
||||
|
||||
BUF_MEM *bptr;
|
||||
|
||||
BIO_get_mem_ptr(mem, &bptr);
|
||||
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
|
||||
BIO_free(mem);
|
||||
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2019 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
|
||||
@@ -0,0 +1,44 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_s_null - null data sink
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
const BIO_METHOD *BIO_s_null(void);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_s_null() returns the null sink BIO method. Data written to
|
||||
the null sink is discarded, reads return EOF.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
A null sink BIO behaves in a similar manner to the Unix /dev/null
|
||||
device.
|
||||
|
||||
A null bio can be placed on the end of a chain to discard any data
|
||||
passed through it.
|
||||
|
||||
A null sink is useful if, for example, an application wishes to digest some
|
||||
data by writing through a digest bio but not send the digested data anywhere.
|
||||
Since a BIO chain must normally include a source/sink BIO this can be achieved
|
||||
by adding a null sink BIO to the end of the chain
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_s_null() returns the null sink BIO method.
|
||||
|
||||
=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
|
||||
@@ -0,0 +1,54 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
BIO_s_socket, BIO_new_socket - socket BIO
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
const BIO_METHOD *BIO_s_socket(void);
|
||||
|
||||
BIO *BIO_new_socket(int sock, int close_flag);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
BIO_s_socket() returns the socket BIO method. This is a wrapper
|
||||
round the platform's socket routines.
|
||||
|
||||
BIO_read_ex() and BIO_write_ex() read or write the underlying socket.
|
||||
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_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
Socket BIOs also support any relevant functionality of file descriptor
|
||||
BIOs.
|
||||
|
||||
The reason for having separate file descriptor and socket BIOs is that on some
|
||||
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.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_s_socket() returns the socket BIO method.
|
||||
|
||||
BIO_new_socket() returns the newly allocated BIO or NULL is an error
|
||||
occurred.
|
||||
|
||||
=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
|
||||
@@ -0,0 +1,240 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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>
|
||||
|
||||
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);
|
||||
|
||||
void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
|
||||
BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
|
||||
|
||||
void BIO_set_callback(BIO *b, BIO_callback_fn cb);
|
||||
BIO_callback_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_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 compatibility. 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 it is interpreted as a BIO to send the information
|
||||
to, otherwise stderr is used.
|
||||
|
||||
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 4
|
||||
|
||||
=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.
|
||||
|
||||
=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 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.
|
||||
|
||||
=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_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
|
||||
|
||||
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, NULL)
|
||||
|
||||
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)
|
||||
|
||||
after.
|
||||
|
||||
=item B<BIO_write(b, data, dlen, written)>
|
||||
|
||||
callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, NULL)
|
||||
|
||||
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)
|
||||
|
||||
after.
|
||||
|
||||
=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)
|
||||
|
||||
after.
|
||||
|
||||
=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_PUTS|BIO_CB_RETURN, buf, 0, 0L, retvalue)
|
||||
|
||||
after.
|
||||
|
||||
=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
|
||||
|
||||
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.
|
||||
|
||||
Note: B<cmd> == B<BIO_CTRL_SET_CALLBACK> is special, because B<parg> is not the
|
||||
argument of type B<BIO_info_cb> itself. In this case B<parg> is a pointer to
|
||||
the actual call parameter, see B<BIO_callback_ctrl>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_get_callback_ex() and BIO_get_callback() return the callback function
|
||||
previously set by a call to BIO_set_callback_ex() and BIO_set_callback()
|
||||
respectively.
|
||||
|
||||
BIO_get_callback_arg() returns a B<char> pointer to the value previously set
|
||||
via a call to BIO_set_callback_arg().
|
||||
|
||||
BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
|
||||
operations.
|
||||
|
||||
=head1 EXAMPLES
|
||||
|
||||
The BIO_debug_callback() function is a good example, its source is
|
||||
in crypto/bio/bio_cb.c
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2020 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
|
||||
@@ -0,0 +1,147 @@
|
||||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
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_set_retry_reason - BIO retry
|
||||
functions
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/bio.h>
|
||||
|
||||
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);
|
||||
|
||||
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
|
||||
|
||||
These functions determine why a BIO is not able to read or write data.
|
||||
They will typically be called after a failed BIO_read_ex() or BIO_write_ex()
|
||||
call.
|
||||
|
||||
BIO_should_retry() is true if the call that produced this condition
|
||||
should then be retried at a later time.
|
||||
|
||||
If BIO_should_retry() is false then the cause is an error condition.
|
||||
|
||||
BIO_should_read() is true if the cause of the condition is that the BIO
|
||||
has insufficient data to return. Check for readability and/or retry the
|
||||
last operation.
|
||||
|
||||
BIO_should_write() is true if the cause of the condition is that the BIO
|
||||
has pending data to write. Check for writability and/or retry the
|
||||
last operation.
|
||||
|
||||
BIO_should_io_special() is true if some "special" condition, that is a
|
||||
reason other than reading or writing is the cause of the condition.
|
||||
|
||||
BIO_retry_type() returns a mask of the cause of a retry condition
|
||||
consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
|
||||
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
|
||||
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.
|
||||
|
||||
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_ex() on a socket BIO returns
|
||||
0 and BIO_should_retry() is false then the cause will be that the
|
||||
connection closed. A similar condition on a file BIO will mean that it
|
||||
has reached EOF. Some BIO types may place additional information on
|
||||
the error queue. For more details see the individual BIO type manual
|
||||
pages.
|
||||
|
||||
If the underlying I/O structure is in a blocking mode almost all current
|
||||
BIO types will not request a retry, because the underlying I/O
|
||||
calls will not. If the application knows that the BIO type will never
|
||||
signal a retry then it need not call BIO_should_retry() after a failed
|
||||
BIO I/O call. This is typically done with file BIOs.
|
||||
|
||||
SSL BIOs are the only current exception to this rule: they can request a
|
||||
retry even if the underlying I/O structure is blocking, if a handshake
|
||||
occurs during a call to BIO_read(). An application can retry the failed
|
||||
call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
|
||||
on the underlying SSL structure.
|
||||
|
||||
While an application may retry a failed non blocking call immediately
|
||||
this is likely to be very inefficient because the call will fail
|
||||
repeatedly until data can be processed or is available. An application
|
||||
will normally wait until the necessary condition is satisfied. How
|
||||
this is done depends on the underlying I/O structure.
|
||||
|
||||
For example if the cause is ultimately a socket and BIO_should_read()
|
||||
is true then a call to select() may be made to wait until data is
|
||||
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.
|
||||
|
||||
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
|
||||
the platforms I/O functions. This is often not desirable: one solution
|
||||
is to use non blocking I/O and use a timeout on the select() (or
|
||||
equivalent) call.
|
||||
|
||||
=head1 BUGS
|
||||
|
||||
The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
|
||||
that is they cannot retry after a partial read or write. This is usually
|
||||
worked around by only passing the relevant data to ASN1 functions when
|
||||
the entire structure can be read or written.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BIO_should_read(), BIO_should_write(), BIO_should_io_special(), and
|
||||
BIO_should_retry() return either 1 or 0 based on the actual conditions
|
||||
of the B<BIO>.
|
||||
|
||||
BIO_retry_type() returns a flag combination presenting the cause of a retry
|
||||
condition or false if there is no retry condition.
|
||||
|
||||
BIO_get_retry_BIO() returns a valid B<BIO> structure.
|
||||
|
||||
BIO_get_retry_reason() returns the reason for a special condition.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<bio>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
|
||||
OpenSSL 1.1.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2000-2018 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
|
||||
@@ -0,0 +1,126 @@
|
||||
=pod
|
||||
|
||||
=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_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);
|
||||
void BN_BLINDING_free(BN_BLINDING *b);
|
||||
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);
|
||||
int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
|
||||
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);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
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
|
||||
necessary parameters are set, by re-creating the blinding parameters.
|
||||
|
||||
BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
|
||||
If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
|
||||
returned in B<r> (this is useful if a B<RSA> object is shared among
|
||||
several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
|
||||
inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
|
||||
the inverse blinding.
|
||||
|
||||
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_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
|
||||
B<BN_BLINDING_NO_RECREATE>. B<BN_BLINDING_NO_UPDATE> inhibits the
|
||||
automatic update of the B<BN_BLINDING> parameters after each use
|
||||
and B<BN_BLINDING_NO_RECREATE> inhibits the automatic re-creation
|
||||
of the B<BN_BLINDING> parameters after a fixed number of uses (currently
|
||||
32). In newly allocated B<BN_BLINDING> objects no flags are set.
|
||||
BN_BLINDING_set_flags() sets the B<BN_BLINDING> parameters flags.
|
||||
|
||||
BN_BLINDING_create_param() creates new B<BN_BLINDING> parameters
|
||||
using the exponent B<e> and the modulus B<m>. B<bn_mod_exp> and
|
||||
B<m_ctx> can be used to pass special functions for exponentiation
|
||||
(normally BN_mod_exp_mont() and B<BN_MONT_CTX>).
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
BN_BLINDING_new() returns the newly allocated B<BN_BLINDING> structure
|
||||
or NULL in case of an error.
|
||||
|
||||
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_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>
|
||||
parameters or NULL on error.
|
||||
|
||||
=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().
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2005-2017 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
Reference in New Issue
Block a user