Hakase/openssl-custom
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

Update - OpenSSL 1.1.1-pre7-dev

Browse Source
This commit is contained in:
Hakase
2018-05-23 23:52:41 +09:00
parent e8a0afd4a0
commit ef253190c7
624 changed files with 189420 additions and 8064 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man7/Ed25519.pod
+10
View File
@@ -39,6 +39,16 @@ For the B<Ed448> algorithm a context can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL);
Ed25519 or Ed448 private keys can be set directly using
L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
can also be generated (see the example below). Setting a private key also sets
the associated public key.
Ed25519 or Ed448 public keys can be set directly using
L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
=head1 EXAMPLE
This example generates an B<ED25519> private key and writes it to standard
doc/man7/RAND.pod
+78
View File
@@ -0,0 +1,78 @@
=pod
=head1 NAME
RAND
- the OpenSSL random generator
=head1 DESCRIPTION
Random numbers are a vital part of cryptography, they are needed to provide
unpredictability for tasks like key generation, creating salts, and many more.
Software-based generators must be seeded with external randomness before they
can be used as a cryptographically-secure pseudo-random number generator
(CSPRNG).
The availability of common hardware with special instructions and
modern operating systems, which may use items such as interrupt jitter
and network packet timings, can be reasonable sources of seeding material.
OpenSSL comes with a default implementation of the RAND API which is based on
the deterministic random bit generator (DRBG) model as described in
[NIST SP 800-90A Rev. 1]. The default random generator will initialize
automatically on first use and will be fully functional without having
to be initialized ('seeded') explicitly.
It seeds and reseeds itself automatically using trusted random sources
provided by the operating system.
As a normal application developer, you don't have to worry about any details,
just use L<RAND_bytes(3)> to obtain random data.
Having said that, there is one important rule to obey: Always check the error
return value of L<RAND_bytes(3)> and don't take randomness for granted.
For long-term secrets, you can use L<RAND_priv_bytes(3)> instead.
This method does not provide 'better' randomness, it uses the same type of CSPRNG.
The intention behind using a dedicated CSPRNG exclusively for long-term secrets is
that none of its output should be visible to an attacker (e.g used as salt value),
in order to reveal as little information as possible about its internal state.
In the rare case where the default implementation does not satisfy your special
requirements, there are two options:
=over 2
=item *
Replace the default RAND method by your own RAND method using
L<RAND_set_rand_method(3)>.
=item *
Modify the default settings of the OpenSSL RAND method by modifying the security
parameters of the underlying DRBG, which is described in detail in L<RAND_DRBG(7)>.
=back
Changing the default random generator or its default parameters should be necessary
only in exceptional cases and is not recommended, unless you have a profound knowledge
of cryptographic principles and understand the implications of your changes.
=head1 SEE ALSO
L<RAND_add(3)>,
L<RAND_bytes(3)>,
L<RAND_priv_bytes(3)>,
L<RAND_get_rand_method(3)>
L<RAND_set_rand_method(3)>
L<RAND_OpenSSL(3)>,
L<RAND_DRBG(7)>,
=head1 COPYRIGHT
Copyright 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
doc/man7/RAND_DRBG.pod
+301
View File
@@ -0,0 +1,301 @@
=pod
=head1 NAME
RAND_DRBG - the deterministic random bit generator
=head1 SYNOPSIS
#include <openssl/rand_drbg.h>
=head1 DESCRIPTION
The default OpenSSL RAND method is based on the RAND_DRBG class,
which implements a deterministic random bit generator (DRBG).
A DRBG is a certain type of cryptographically-secure pseudo-random
number generator (CSPRNG), which is described in
[NIST SP 800-90A Rev. 1].
While the RAND API is the 'frontend' which is intended to be used by
application developers for obtaining random bytes, the RAND_DRBG API
serves as the 'backend', connecting the former with the operating
systems's entropy sources and providing access to the DRBG's
configuration parameters.
=head2 Disclaimer
Unless you have very specific requirements for your random generator,
it is in general not necessary to utilize the RAND_DRBG API directly.
The usual way to obtain random bytes is to use L<RAND_bytes(3)> or
L<RAND_priv_bytes(3)>, see also L<RAND(7)>.
=head2 Typical Use Cases
Typical examples for such special use cases are the following:
=over 2
=item *
You want to use your own private DRBG instances.
Multiple DRBG instances which are accessed only by a single thread provide
additional security (because their internal states are independent) and
better scalability in multithreaded applications (because they don't need
to be locked).
=item *
You need to integrate a previously unsupported entropy source.
=item *
You need to change the default settings of the standard OpenSSL RAND
implementation to meet specific requirements.
=back
=head1 CHAINING
A DRBG instance can be used as the entropy source of another DRBG instance,
provided it has itself access to a valid entropy source.
The DRBG instance which acts as entropy source is called the I<parent> DRBG,
the other instance the I<child> DRBG.
This is called chaining. A chained DRBG instance is created by passing
a pointer to the parent DRBG as argument to the RAND_DRBG_new() call.
It is possible to create chains of more than two DRBG in a row.
=head1 THE THREE SHARED DRBG INSTANCES
Currently, there are three shared DRBG instances,
the <master>, <public>, and <private> DRBG.
While the <master> DRBG is a single global instance, the <public> and <private>
DRBG are created per thread and accessed through thread-local storage.
By default, the functions L<RAND_bytes(3)> and L<RAND_priv_bytes(3)> use
the thread-local <public> and <private> DRBG instance, respectively.
=head2 The <master> DRBG instance
The <master> DRBG is not used directly by the application, only for reseeding
the two other two DRBG instances. It reseeds itself by obtaining randomness
either from os entropy sources or by consuming randomness which was added
previously by L<RAND_add(3)>.
=head2 The <public> DRBG instance
This instance is used per default by L<RAND_bytes(3)>.
=head2 The <private> DRBG instance
This instance is used per default by L<RAND_priv_bytes(3)>
=head1 LOCKING
The <master> DRBG is intended to be accessed concurrently for reseeding
by its child DRBG instances. The necessary locking is done internally.
It is I<not> thread-safe to access the <master> DRBG directly via the
RAND_DRBG interface.
The <public> and <private> DRBG are thread-local, i.e. there is an
instance of each per thread. So they can safely be accessed without
locking via the RAND_DRBG interface.
Pointers to these DRBG instances can be obtained using
RAND_DRBG_get0_master(),
RAND_DRBG_get0_public(), and
RAND_DRBG_get0_private(), respectively.
Note that it is not allowed to store a pointer to one of the thread-local
DRBG instances in a variable or other memory location where it will be
accessed and used by multiple threads.
All other DRBG instances created by an application don't support locking,
because they are intended to be used by a single thread.
Instead of accessing a single DRBG instance concurrently from different
threads, it is recommended to instantiate a separate DRBG instance per
thread. Using the <master> DRBG as entropy source for multiple DRBG
instances on different threads is thread-safe, because the DRBG instance
will lock the <master> DRBG automatically for obtaining random input.
=head1 THE OVERALL PICTURE
The following picture gives an overview over how the DRBG instances work
together and are being used.
+--------------------+
| os entropy sources |
+--------------------+
|
v +-----------------------------+
RAND_add() ==> <master> <-| shared DRBG (with locking) |
/ \ +-----------------------------+
/ \ +---------------------------+
<public> <private> <- | per-thread DRBG instances |
| | +---------------------------+
v v
RAND_bytes() RAND_priv_bytes()
| ^
| |
+------------------+ +------------------------------------+
| general purpose | | used for secrets like session keys |
| random generator | | and private keys for certificates |
+------------------+ +------------------------------------+
The usual way to obtain random bytes is to call RAND_bytes(...) or
RAND_priv_bytes(...). These calls are roughly equivalent to calling
RAND_DRBG_bytes(<public>, ...) and RAND_DRBG_bytes(<private>, ...),
respectively. The method L<RAND_DRBG_bytes(3)> is a convenience method
wrapping the L<RAND_DRBG_generate(3)> function, which serves the actual
request for random data.
=head1 RESEEDING
A DRBG instance seeds itself automatically, pulling random input from
its entropy source. The entropy source can be either a trusted operating
system entropy source, or another DRBG with access to such a source.
Automatic reseeding occurs after a predefined number of generate requests.
The selection of the trusted entropy sources is configured at build
time using the --with-rand-seed option. The following sections explain
the reseeding process in more detail.
=head2 Automatic Reseeding
Before satisfying a generate request (L<RAND_DRBG_generate(3)>), the DRBG
reseeds itself automatically, if one of the following conditions holds:
- the DRBG was not instantiated (=seeded) yet or has been uninstantiated.
- the number of generate requests since the last reseeding exceeds a
certain threshold, the so called I<reseed_interval>.
This behaviour can be disabled by setting the I<reseed_interval> to 0.
- the time elapsed since the last reseeding exceeds a certain time
interval, the so called I<reseed_time_interval>.
This can be disabled by setting the I<reseed_time_interval> to 0.
- the DRBG is in an error state.
B<Note>: An error state is entered if the entropy source fails while
the DRBG is seeding or reseeding.
The last case ensures that the DRBG automatically recovers
from the error as soon as the entropy source is available again.
=head2 Manual Reseeding
In addition to automatic reseeding, the caller can request an immediate
reseeding of the DRBG with fresh entropy by setting the
I<prediction resistance> parameter to 1 when calling L<RAND_DRBG_generate(3)>.
The dcoument [NIST SP 800-90C] describes prediction resistance requests
in detail and imposes strict conditions on the entropy sources that are
approved for providing prediction resistance.
Since the default DRBG implementation does not have access to such an approved
entropy source, a request for prediction resistance will currently always fail.
In other words, prediction resistance is currently not supported yet by the DRBG.
For the three shared DRBGs (and only for these) there is another way to
reseed them manually:
If L<RAND_add(3)> is called with a positive I<randomness> argument
(or L<RAND_seed(3)>), then this will immediately reseed the <master> DRBG.
The <public> and <private> DRBG will detect this on their next generate
call and reseed, pulling randomness from <master>.
The last feature has been added to support the common practice used with
previous OpenSSL versions to call RAND_add() before calling RAND_bytes().
=head2 Entropy Input vs. Additional Data
The DRBG distinguishes two different types of random input: I<entropy>,
which comes from a trusted source, and I<additional input>',
which can optionally be added by the user and is considered untrusted.
It is possible to add I<additional input> not only during reseeding,
but also for every generate request.
This is in fact done automatically by L<RAND_DRBG_bytes(3)>.
=head2 Configuring the Random Seed Source
In most cases OpenSSL will automatically choose a suitable seed source
for automatically seeding and reseeding its <master> DRBG. In some cases
however, it will be necessary to explicitely specify a seed source during
configuration, using the --with-rand-seed option. For more information,
see the INSTALL instructions. There are also operating systems where no
seed source is available and automatic reseeding is disabled by default.
The following two sections describe the reseeding process of the master
DRBG, depending on whether automatic reseeding is available or not.
=head2 Reseeding the master DRBG with automatic seeding enabled
Calling RAND_poll() or RAND_add() is not necessary, because the DRBG
pulls the necessary entropy from its source automatically.
However, both calls are permitted, and do reseed the RNG.
RAND_add() can be used to add both kinds of random input, depending on the
value of the B<randomness> argument:
=over 4
=item randomness == 0:
The random bytes are mixed as additional input into the current state of
the DRBG.
Mixing in additional input is not considered a full reseeding, hence the
reseed counter is not reset.
=item randomness > 0:
The random bytes are used as entropy input for a full reseeding
(resp. reinstantiation) if the DRBG is instantiated
(resp. uninstantiated or in an error state).
The number of random bits required for reseeding is determined by the
security strength of the DRBG. Currently it defaults to 256 bits (32 bytes).
It is possible to provide less randomness than required.
In this case the missing randomness will be obtained by pulling random input
from the trusted entropy sources.
=back
=head2 Reseeding the master DRBG with automatic seeding disabled
Calling RAND_poll() will always fail.
RAND_add() needs to be called for initial seeding and periodic reseeding.
At least 48 bytes (384 bits) of randomness have to be provided, otherwise
the (re-)seeding of the DRBG will fail. This corresponds to one and a half
times the security strength of the DRBG. The extra half is used for the
nonce during instantiation.
More precisely, the number of bytes needed for seeding depend on the
I<security strength> of the DRBG, which is set to 256 by default.
=head1 SEE ALSO
L<RAND_DRBG_bytes(3)>,
L<RAND_DRBG_generate(3)>,
L<RAND_DRBG_reseed(3)>,
L<RAND_DRBG_get0_master(3)>,
L<RAND_DRBG_get0_public(3)>,
L<RAND_DRBG_get0_private(3)>,
L<RAND_DRBG_set_reseed_interval(3)>,
L<RAND_DRBG_set_reseed_time_interval(3)>,
L<RAND_DRBG_set_reseed_defaults(3)>,
L<RAND(7)>,
=head1 COPYRIGHT
Copyright 2017-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
doc/man7/RSA-PSS.pod
+9 -59
View File
@@ -4,17 +4,6 @@
RSA-PSS - EVP_PKEY RSA-PSS algorithm support
=head1 SYNOPSIS
#include <openssl/rsa.h>
int EVP_PKEY_CTX_set_rsa_pss_keygen_md(EVP_PKEY_CTX *pctx,
const EVP_MD *md);
int EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(EVP_PKEY_CTX *pctx,
const EVP_MD *md);
int EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(EVP_PKEY_CTX *pctx,
int saltlen);
=head1 DESCRIPTION
The B<RSA-PSS> EVP_PKEY implementation is a restricted version of the RSA
@@ -26,7 +15,7 @@ It has associated private key and public key formats.
This algorithm shares several control operations with the B<RSA> algorithm
but with some restrictions described below.
=head1 SIGNING AND VERIFICATION
=head2 Signing and Verification
Signing and verification is similar to the B<RSA> algorithm except the
padding mode is always PSS. If the key in use has parameter restrictions then
@@ -35,73 +24,34 @@ for example, if the key can only be used with digest SHA256, MGF1 SHA256
and minimum salt length 32 then the digest, MGF1 digest and salt length
will be set to SHA256, SHA256 and 32 respectively.
The macro EVP_PKEY_CTX_set_rsa_padding() is supported but an error is
returned if an attempt is made to set the padding mode to anything other
than B<PSS>. It is otherwise similar to the B<RSA> version.
=head2 Key Generation
The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length.
If the key has usage restrictions then an error is returned if an attempt is
made to set the salt length below the minimum value. It is otherwise similar
to the B<RSA> operation except detection of the salt length (using
RSA_PSS_SALTLEN_AUTO is not supported for verification if the key has
usage restrictions.
The EVP_PKEY_CTX_set_signature_md() and EVP_PKEY_CTX_set_rsa_mgf1_md() macros
are used to set the digest and MGF1 algorithms respectively. If the key has
usage restrictions then an error is returned if an attempt is made to set the
digest to anything other than the restricted value. Otherwise these are
similar to the B<RSA> versions.
=head1 KEY GENERATION
As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits()
and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA-PSS:
they have exactly the same meaning as for the RSA algorithm.
Optional parameter restrictions can be specified when generating a PSS key. By
default no parameter restrictions are placed on the generated key. If any
restrictions are set (using the macros described below) then B<all> parameters
are restricted. For example, setting a minimum salt length also restricts the
digest and MGF1 algorithms. If any restrictions are in place then they are
reflected in the corresponding parameters of the public key when (for example)
a certificate request is signed.
EVP_PKEY_CTX_set_rsa_pss_keygen_md() restricts the digest algorithm the
generated key can use to B<md>.
EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md() restricts the MGF1 algorithm the
generated key can use to B<md>.
EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen() restricts the minimum salt length
to B<saltlen>.
By default no parameter restrictions are placed on the generated key.
=head1 NOTES
A context for the B<RSA-PSS> algorithm can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA_PSS, NULL);
The public key format is documented in RFC4055.
The PKCS#8 private key format used for RSA-PSS keys is similar to the RSA
format except it uses the B<id-RSASSA-PSS> OID and the parameters field, if
present, restricts the key parameters in the same way as the public key.
=head1 RETURN VALUES
=head1 CONFORMING TO
All these functions return 1 for success and 0 or a negative value for failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
RFC 4055
=head1 SEE ALSO
L<EVP_PKEY_CTX_set_rsa_pss_keygen_md(3)>,
L<EVP_PKEY_CTX_set_rsa_pss_keygen_mgf1_md(3)>,
L<EVP_PKEY_CTX_set_rsa_pss_keygen_saltlen(3)>,
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl_str(3)>,
L<EVP_PKEY_derive(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-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
doc/man7/X25519.pod
+10
View File
@@ -27,6 +27,16 @@ For the B<X448> algorithm a context can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X448, NULL);
X25519 or X448 private keys can be set directly using
L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
can also be generated (see the example below). Setting a private key also sets
the associated public key.
X25519 or X448 public keys can be set directly using
L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
=head1 EXAMPLE
This example generates an B<X25519> private key and writes it to standard
doc/man7/passphrase-encoding.pod
+182
View File
@@ -0,0 +1,182 @@
=pod
=encoding utf8
=head1 NAME
password encoding
- How diverse parts of OpenSSL treat pass phrases character encoding
=head1 DESCRIPTION
In a modern world with all sorts of character encodings, the treatment of pass
phrases has become increasingly complex.
This manual page attempts to give an overview over how this problem is
currently addressed in different parts of the OpenSSL library.
=head2 The general case
The OpenSSL library doesn't treat pass phrases in any special way as a general
rule, and trusts the application or user to choose a suitable character set
and stick to that throughout the lifetime of affected objects.
This means that for an object that was encrypted using a pass phrase encoded in
ISO-8859-1, that object needs to be decrypted using a pass phrase encoded in
ISO-8859-1.
Using the wrong encoding is expected to cause a decryption failure.
=head2 PKCS#12
PKCS#12 is a bit different regarding pass phrase encoding.
The standard stipulates that the pass phrase shall be encoded as an ASN.1
BMPString, which consists of the code points of the basic multilingual plane,
encoded in big endian (UCS-2 BE).
OpenSSL tries to adapt to this requirements in one of the following manners:
=over 4
=item 1.
Treats the received pass phrase as UTF-8 encoded and tries to re-encode it to
UTF-16 (which is the same as UCS-2 for characters U+0000 to U+D7FF and U+E000
to U+FFFF, but becomes an expansion for any other character), or failing that,
proceeds with step 2.
=item 2.
Assumes that the pass phrase is encoded in ASCII or ISO-8859-1 and
opportunistically prepends each byte with a zero byte to obtain the UCS-2
encoding of the characters, which it stores as a BMPString.
Note that since there is no check of your locale, this may produce UCS-2 /
UTF-16 characters that do not correspond to the original pass phrase characters
for other character sets, such as any ISO-8859-X encoding other than
ISO-8859-1 (or for Windows, CP 1252 with exception for the extra "graphical"
characters in the 0x80-0x9F range).
=back
OpenSSL versions older than 1.1.0 do variant 2 only, and that is the reason why
OpenSSL still does this, to be able to read files produced with older versions.
It should be noted that this approach isn't entirely fault free.
A passphrase encoded in ISO-8859-2 could very well have a sequence such as
0xC3 0xAF (which is the two characters "LATIN CAPITAL LETTER A WITH BREVE"
and "LATIN CAPITAL LETTER Z WITH DOT ABOVE" in ISO-8859-2 encoding), but would
be misinterpreted as the perfectly valid UTF-8 encoded code point U+00EF (LATIN
SMALL LETTER I WITH DIARESIS) I<if the passphrase doesn't contain anything that
would be invalid UTF-8>.
A pass phrase that contains this kind of byte sequence will give a different
outcome in OpenSSL 1.1.0 and newer than in OpenSSL older than 1.1.0.
0x00 0xC3 0x00 0xAF # OpenSSL older than 1.1.0
0x00 0xEF # OpenSSL 1.1.0 and newer
On the same accord, anything encoded in UTF-8 that was given to OpenSSL older
than 1.1.0 was misinterpreted as ISO-8859-1 sequences.
=head2 OSSL_STORE
L<ossl_store(7)> acts as a general interface to access all kinds of objects,
potentially protected with a pass phrase, a PIN or something else.
This API currently doesn't stipulate any specific encoding of pass phrases, but
uses the underlying routines with their behaviours.
This means that when using the built-in C<file:> scheme loader, the pass phrase
to unlock a PKCS#12 file will be treated as described for PKCS#12 above, and
the pass phrase for a PEM files will be treated as the general case described
above, since that loader uses the same underlying routines.
I<Note that other loaders will have their own behaviours>.
=head1 RECOMMENDATIONS
This section assumes that you know what pass phrase was used for encryption,
but that it may have been encoded in a different character encoding than the
one used by your current input method.
For example, the pass phrase may have been used at a time when your default
encoding was ISO-8859-1 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61
0xEF 0x76 0x65), and you're now in an environment where your default encoding
is UTF-8 (i.e. "naïve" resulting in the byte sequence 0x6E 0x61 0xC3 0xAF 0x76
0x65).
Whenever it's mentioned that you should use a certain character encoding, it
should be understood that you either change the input method to use the
mentioned encoding when you type in your pass phrase, or use some suitable tool
to convert your pass phrase from your default encoding to the target encoding.
Also note that the sub-sections below discuss human readable pass phrases.
This is particularly relevant for PKCS#12 objects, where human readable pass
phrases are assumed.
For other objects, it's as legitimate to use any byte sequence (such as a
sequence of bytes from `/dev/urandom` that's been saved away), which makes any
character encoding discussion irrelevant; in such cases, simply use the same
byte sequence as it is.
=head2 Creating new objects
For creating new pass phrase protected objects, make sure the pass phrase is
encoded using UTF-8.
This is default on most modern Unixes, but may involve an effort on other
platforms.
Specifically for Windows, setting the environment variable
C<OPENSSL_WIN32_UTF8> will have anything entered on [Windows] console prompt
converted to UTF-8 (command line and separately prompted pass phrases alike).
=head2 Opening existing objects
For opening pass phrase protected objects where you know what character
encoding was used for the encryption pass phrase, make sure to use the same
encoding again.
For opening pass phrase protected objects where the character encoding that was
used is unknown, or where the producing application is unknown, try one of the
following:
=over 4
=item 1.
Try the password that you have as it is in the character encoding of your
environment.
It's possible that its byte sequence is exactly right.
=item 2.
Convert the pass phrase to UTF-8 and try with the result.
Specifically with PKCS#12, this should open up any object that was created
according to the specification.
=item 3.
Do a naïve (i.e. purely mathematical) ISO-8859-1 to UTF-8 conversion and try
with the result.
This differs from the previous attempt because ISO-8859-1 maps directly to
U+0000 to U+00FF, which other non-UTF-8 character sets do not.
This also takes care of the case when a UTF-8 encoded string was used with
OpenSSL older than 1.1.0.
(for example, C<ï>, which is 0xC3 0xAF when encoded in UTF-8, would become 0xC3
0x83 0xC2 0xAF when re-encoded in the naïve manner.
The conversion to BMPString would then yield 0x00 0xC3 0x00 0xA4 0x00 0x00, the
erroneous/non-compliant encoding used by OpenSSL older than 1.1.0)
=back
=head1 SEE ALSO
L<evp(7)>,
L<ossl_store(7)>,
L<EVP_BytesToKey(3)>, L<EVP_DecryptInit(3)>,
L<PEM_do_header(3)>,
L<PKCS12_parse(3)>, L<PKCS12_newpass(3)>,
L<d2i_PKCS8PrivateKey_bio(3)>
=head1 COPYRIGHT
Copyright 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
doc/man7/scrypt.pod
+9 -52
View File
@@ -4,24 +4,6 @@
scrypt - EVP_PKEY scrypt KDF support
=head1 SYNOPSIS
#include <openssl/kdf.h>
int EVP_PKEY_CTX_set1_pbe_pass(EVP_PKEY_CTX *pctx, unsigned char *pass,
int passlen);
int EVP_PKEY_CTX_set1_scrypt_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
int saltlen);
int EVP_PKEY_CTX_set_scrypt_N(EVP_PKEY_CTX *pctx, uint64_t N);
int EVP_PKEY_CTX_set_scrypt_r(EVP_PKEY_CTX *pctx, uint64_t r);
int EVP_PKEY_CTX_set_scrypt_p(EVP_PKEY_CTX *pctx, uint64_t p);
int EVP_PKEY_CTX_set_scrypt_maxmem_bytes(EVP_PKEY_CTX *pctx, uint64_t maxmem);
=head1 DESCRIPTION
The EVP_PKEY_SCRYPT algorithm implements the scrypt password based key
@@ -47,44 +29,14 @@ GHz), this computation takes about 3 seconds. When N, r or p are not specified,
they default to 1048576, 8, and 1, respectively. The default amount of RAM that
may be used by scrypt defaults to 1025 MiB.
EVP_PKEY_CTX_set1_pbe_pass() sets the B<passlen> bytes long password.
EVP_PKEY_CTX_set1_scrypt_salt() sets the B<saltlen> bytes long salt value.
EVP_PKEY_CTX_set_scrypt_N(), EVP_PKEY_CTX_set_scrypt_r() and
EVP_PKEY_CTX_set_scrypt_p() configure the work factors N, r and p.
EVP_PKEY_CTX_set_scrypt_maxmem_bytes() sets how much RAM key derivation may
maximally use, given in bytes. If RAM is exceeded because the load factors are
chosen too high, the key derivation will fail.
=head1 STRING CTRLS
scrypt also supports string based control operations via
L<EVP_PKEY_CTX_ctrl_str(3)>.
The B<password> can be directly specified using the B<type> parameter "pass" or
given in hex encoding using the "hexpass" parameter. Similarly, the B<salt> can
either be specified using the B<type> parameter "salt" or in hex encoding by
using the "hexsalt" parameter. The work factors B<N>, B<r> and B<p> as well as
B<maxmem_bytes> can be set by using the parameters "N", "r", "p" and
"maxmem_bytes", respectively.
=head1 NOTES
All these functions are implemented as macros.
A context for scrypt can be obtained by calling:
EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_SCRYPT, NULL);
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
The output length of an scrypt key derivation is specified via the length
parameter to the L<EVP_PKEY_derive(3)> function.
=head1 RETURN VALUES
All these functions return 1 for success and 0 or a negative value for failure.
In particular a return value of -2 indicates the operation is not supported by
the public key algorithm.
The output length of an scrypt key derivation is specified via the
length parameter to the L<EVP_PKEY_derive(3)> function.
=head1 EXAMPLE
@@ -142,13 +94,18 @@ RFC 7914
=head1 SEE ALSO
L<EVP_PKEY_CTX_set1_scrypt_salt(3)>,
L<EVP_PKEY_CTX_set_scrypt_N(3)>,
L<EVP_PKEY_CTX_set_scrypt_r(3)>,
L<EVP_PKEY_CTX_set_scrypt_p(3)>,
L<EVP_PKEY_CTX_set_scrypt_maxmem_bytes(3)>,
L<EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl_str(3)>,
L<EVP_PKEY_derive(3)>
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2017-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
doc/man7/ssl.pod
+1 -7
View File
@@ -89,12 +89,6 @@ includes both more private SSL headers and headers from the B<crypto> library.
Whenever you need hard-core details on the internals of the SSL API, look
inside this header file.
OPENSSL_VERSION_AT_LEAST(major,minor) can be
used in C<#if> statements in order to determine which version of the library is
being used. This can be used to either enable optional features at compile
time, or work around issues with a previous version.
See L<OPENSSL_VERSION_NUMBER(3)>.
=item B<ssl2.h>
Unused. Present for backwards compatibility only.
@@ -576,7 +570,7 @@ fresh handle for each connection.
=item SSL_SESSION *B<SSL_get_session>(const SSL *ssl);
=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int len);
=item char *B<SSL_get_shared_ciphers>(const SSL *ssl, char *buf, int size);
=item int B<SSL_get_shutdown>(const SSL *ssl);