aboutsummaryrefslogtreecommitdiff
path: root/openssl/doc
diff options
context:
space:
mode:
Diffstat (limited to 'openssl/doc')
-rw-r--r--openssl/doc/apps/c_rehash.pod81
-rw-r--r--openssl/doc/apps/dgst.pod68
-rw-r--r--openssl/doc/crypto/BIO_s_accept.pod4
-rw-r--r--openssl/doc/crypto/CMS_add1_signer.pod (renamed from openssl/doc/crypto/CMS_sign_add1_signer.pod)14
-rw-r--r--openssl/doc/crypto/EVP_DigestInit.pod30
-rw-r--r--openssl/doc/crypto/EVP_DigestVerifyInit.pod4
-rw-r--r--openssl/doc/crypto/EVP_EncryptInit.pod56
-rw-r--r--openssl/doc/crypto/EVP_PKEY_set1_RSA.pod8
-rw-r--r--openssl/doc/crypto/EVP_PKEY_sign.pod20
-rw-r--r--openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod15
10 files changed, 213 insertions, 87 deletions
diff --git a/openssl/doc/apps/c_rehash.pod b/openssl/doc/apps/c_rehash.pod
new file mode 100644
index 000000000..c564e8631
--- /dev/null
+++ b/openssl/doc/apps/c_rehash.pod
@@ -0,0 +1,81 @@
+=pod
+
+=for comment
+Original text by James Westby, contributed under the OpenSSL license.
+
+=head1 NAME
+
+c_rehash - Create symbolic links to files named by the hash values
+
+=head1 SYNOPSIS
+
+B<c_rehash>
+[ I<directory>...]
+
+=head1 DESCRIPTION
+
+B<c_rehash> scans directories and calculates a hash value of each C<.pem>
+file in the specified directory list and creates symbolic links
+for each file, where the name of the link is the hash value.
+This utility is useful as many programs that use OpenSSL require
+directories to be set up like this in order to find certificates.
+
+If any directories are named on the command line, then those are
+processed in turn. If not, then the B<SSL_CERT_DIR> environment variable
+is consulted; this shold be a colon-separated list of directories,
+like the Unix B<PATH> variable.
+If that is not set then the default directory (installation-specific
+but often B</usr/local/ssl/certs>) is processed.
+
+In order for a directory to be processed, the user must have write
+permissions on that directory, otherwise it will be skipped.
+The links created are of the form C<HHHHHHHH.D>, where each B<H>
+is a hexadecimal character and B<D> is a single decimal digit.
+When processing a directory, B<c_rehash> will first remove all links
+that have a name in that syntax. If you have links in that format
+used for other purposes, they will be removed.
+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 B<.pem> files that
+cannot be parsed as either a certificate or a CRL.
+
+The program uses the B<openssl> program to compute the hashes and
+fingerprints. If not found in the user's B<PATH>, then set the
+B<OPENSSL> environment variable to the full pathname.
+Any program can be used, it will be invoked as follows for either
+a certificate or CRL:
+
+ $OPENSSL x509 -hash -fingerprint -noout -in FFFFFF
+ $OPENSSL crl -hash -fingerprint -noout -in FFFFFF
+
+where B<FFFFFF> 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 ENVIRONMENT
+
+=over
+
+=item B<OPENSSL>
+
+The path to an executable to use to generate hashes and
+fingerprints (see above).
+
+=item B<SSL_CERT_DIR>
+
+Colon separated list of directories to operate on.
+Ignored if directories are listed on the command line.
+
+=back
+
+=head1 SEE ALSO
+
+L<openssl(1)|openssl(1)>,
+L<crl(1)|crl(1)>.
+L<x509(1)|x509(1)>.
diff --git a/openssl/doc/apps/dgst.pod b/openssl/doc/apps/dgst.pod
index b035edf08..2414c5337 100644
--- a/openssl/doc/apps/dgst.pod
+++ b/openssl/doc/apps/dgst.pod
@@ -2,16 +2,17 @@
=head1 NAME
-dgst, md5, md4, md2, sha1, sha, mdc2, ripemd160 - message digests
+dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests
=head1 SYNOPSIS
B<openssl> B<dgst>
-[B<-md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1>]
+[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
+[B<-r>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
@@ -20,17 +21,19 @@ B<openssl> B<dgst>
[B<-prverify filename>]
[B<-signature filename>]
[B<-hmac key>]
+[B<-non-fips-allow>]
+[B<-fips-fingerprint>]
[B<file...>]
-[B<md5|md4|md2|sha1|sha|mdc2|ripemd160>]
-[B<-c>]
-[B<-d>]
-[B<file...>]
+B<openssl>
+[I<digest>]
+[B<...>]
=head1 DESCRIPTION
The digest functions output the message digest of a supplied file or files
-in hexadecimal form. They can also be used for digital signing and verification.
+in hexadecimal. The digest functions also generate and verify digital
+signatures using message digests.
=head1 OPTIONS
@@ -48,12 +51,17 @@ print out BIO debugging information.
=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.
+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 used by programs like B<sha1sum>.
+
=item B<-out filename>
filename to output to, or standard output by default.
@@ -64,8 +72,8 @@ digitally sign the digest using the private key in "filename".
=item B<-keyform arg>
-Specifies the key format to sign digest with. Only PEM and ENGINE
-formats are supported by the B<dgst> command.
+Specifies the key format to sign digest with. The DER, PEM, P12,
+and ENGINE formats are supported.
=item B<-engine id>
@@ -117,7 +125,7 @@ Following options are supported by both by B<HMAC> and B<gost-mac>:
=over 8
=item B<key:string>
-
+
Specifies MAC key as alphnumeric string (use if key contain printable
characters only). String length must conform to any restrictions of
the MAC algorithm for example exactly 32 chars for gost-mac.
@@ -138,6 +146,15 @@ Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
+=item B<-non-fips-allow>
+
+enable use of non-FIPS algorithms such as MD5 even in FIPS mode.
+
+=item B<-fips-fingerprint>
+
+compute HMAC using a specific key
+for certain OpenSSL-FIPS operations.
+
=item B<file...>
file or files to digest. If no files are specified then standard input is
@@ -145,18 +162,41 @@ 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 of choice for all new applications is SHA1. Other digests are
however still widely used.
-If you wish to sign or verify data using the DSA algorithm then the dss1
-digest must be used.
+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 DSA.
+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.
+
+
=cut
diff --git a/openssl/doc/crypto/BIO_s_accept.pod b/openssl/doc/crypto/BIO_s_accept.pod
index 7b63e4621..b80b6ae48 100644
--- a/openssl/doc/crypto/BIO_s_accept.pod
+++ b/openssl/doc/crypto/BIO_s_accept.pod
@@ -59,8 +59,8 @@ the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
BIO_set_accept_port() uses the string B<name> to set the accept
port. The port is represented as a string of the form "host:port",
where "host" is the interface to use and "port" is the port.
-Either or both values can be "*" which is interpreted as meaning
-any interface or port respectively. "port" has the same syntax
+The host can be can be "*" which is interpreted as meaning
+any interface; "port" has the same syntax
as the port specified in BIO_set_conn_port() for connect BIOs,
that is it can be a numerical port string or a string to lookup
using getservbyname() and a string table.
diff --git a/openssl/doc/crypto/CMS_sign_add1_signer.pod b/openssl/doc/crypto/CMS_add1_signer.pod
index bda3ca2ad..a055b8269 100644
--- a/openssl/doc/crypto/CMS_sign_add1_signer.pod
+++ b/openssl/doc/crypto/CMS_add1_signer.pod
@@ -2,20 +2,20 @@
=head1 NAME
- CMS_sign_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
+ CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
=head1 SYNOPSIS
#include <openssl/cms.h>
- CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
+ CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
int CMS_SignerInfo_sign(CMS_SignerInfo *si);
=head1 DESCRIPTION
-CMS_sign_add1_signer() adds a signer with certificate B<signcert> and private
+CMS_add1_signer() adds a signer with certificate B<signcert> and private
key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
structure B<cms>.
@@ -36,7 +36,7 @@ are both set.
=head1 NOTES
-The main purpose of CMS_sign_add1_signer() is to provide finer control
+The main purpose of CMS_add1_signer() is to provide finer control
over a CMS signed data structure where the simpler CMS_sign() function defaults
are not appropriate. For example if multiple signers or non default digest
algorithms are needed. New attributes can also be added using the returned
@@ -80,13 +80,13 @@ bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
not loaded.
-CMS_sign_add1_signer() returns an internal pointer to the CMS_SignerInfo
+CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added, this can be used to set additional attributes
before it is finalized.
=head1 RETURN VALUES
-CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo
+CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added or NULL if an error occurs.
=head1 SEE ALSO
@@ -96,6 +96,6 @@ L<CMS_final(3)|CMS_final(3)>,
=head1 HISTORY
-CMS_sign_add1_signer() was added to OpenSSL 0.9.8
+CMS_add1_signer() was added to OpenSSL 0.9.8
=cut
diff --git a/openssl/doc/crypto/EVP_DigestInit.pod b/openssl/doc/crypto/EVP_DigestInit.pod
index 310c65eb3..ac526bb6d 100644
--- a/openssl/doc/crypto/EVP_DigestInit.pod
+++ b/openssl/doc/crypto/EVP_DigestInit.pod
@@ -26,13 +26,13 @@ EVP digest routines
int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
- int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
+ int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);
- int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
+ int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
#define EVP_MAX_MD_SIZE 64 /* SHA512 */
@@ -136,10 +136,10 @@ reasons.
EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(),
EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD>
structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2
-and RIPEMD160 digest algorithms respectively.
+and RIPEMD160 digest algorithms respectively.
EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest
-algorithms but using DSS (DSA) for the signature algorithm. Note: there is
+algorithms but using DSS (DSA) for the signature algorithm. Note: there is
no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are
however retained for compatibility.
@@ -177,21 +177,21 @@ The B<EVP> interface to message digests should almost always be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the digest used and much more flexible.
-New applications should use the SHA2 digest algorithms such as SHA256.
+New applications should use the SHA2 digest algorithms such as SHA256.
The other digest algorithms are still in common use.
For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
set to NULL to use the default digest implementation.
-The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
+The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
obsolete but are retained to maintain compatibility with existing code. New
-applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
+applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
instead of initializing and cleaning it up on each call and allow non default
implementations of digests to be specified.
In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use
-memory leaks will occur.
+memory leaks will occur.
Stack allocation of EVP_MD_CTX structures is common, for example:
@@ -245,15 +245,19 @@ digest name passed on the command line.
EVP_MD_CTX_destroy(mdctx);
printf("Digest is: ");
- for(i = 0; i < md_len; i++) printf("%02x", md_value[i]);
+ for(i = 0; i < md_len; i++)
+ printf("%02x", md_value[i]);
printf("\n");
+
+ /* Call this once before exit. */
+ EVP_cleanup();
+ exit(0);
}
=head1 SEE ALSO
-L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
-L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
-L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
+L<dgst(1)|dgst(1)>,
+L<evp(3)|evp(3)>
=head1 HISTORY
@@ -269,7 +273,7 @@ EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were
changed to return truely const EVP_MD * in OpenSSL 0.9.7.
The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
-later, so now EVP_sha1() can be used with RSA and DSA, there is no need to
+later, so now EVP_sha1() can be used with RSA and DSA; there is no need to
use EVP_dss1() any more.
OpenSSL 1.0 and later does not include the MD2 digest algorithm in the
diff --git a/openssl/doc/crypto/EVP_DigestVerifyInit.pod b/openssl/doc/crypto/EVP_DigestVerifyInit.pod
index f22448897..cfeccd96e 100644
--- a/openssl/doc/crypto/EVP_DigestVerifyInit.pod
+++ b/openssl/doc/crypto/EVP_DigestVerifyInit.pod
@@ -38,7 +38,7 @@ or a negative value for failure. In particular a return value of -2 indicates
the operation is not supported by the public key algorithm.
Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only
-indicates that the signature did not not verify successfully (that is tbs did
+indicates that the signature did not verify successfully (that is tbs did
not match the original data or the signature was of invalid form) it is not an
indication of a more serious error.
@@ -59,7 +59,7 @@ For some key types and parameters the random number generator must be seeded
or the operation will fail.
The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
-context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can
+context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
be called later to digest and verify additional data.
Since only a copy of the digest context is ever finalized the context must
diff --git a/openssl/doc/crypto/EVP_EncryptInit.pod b/openssl/doc/crypto/EVP_EncryptInit.pod
index d11e054e4..4e22edcd6 100644
--- a/openssl/doc/crypto/EVP_EncryptInit.pod
+++ b/openssl/doc/crypto/EVP_EncryptInit.pod
@@ -387,27 +387,7 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
=head1 EXAMPLES
-Get the number of rounds used in RC5:
-
- int nrounds;
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds);
-
-Get the RC2 effective key length:
-
- int key_bits;
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits);
-
-Set the number of rounds used in RC5:
-
- int nrounds;
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL);
-
-Set the effective key length used in RC2:
-
- int key_bits;
- EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL);
-
-Encrypt a string using blowfish:
+Encrypt a string using IDEA:
int do_crypt(char *outfile)
{
@@ -421,8 +401,9 @@ Encrypt a string using blowfish:
char intext[] = "Some Crypto Text";
EVP_CIPHER_CTX ctx;
FILE *out;
+
EVP_CIPHER_CTX_init(&ctx);
- EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
+ EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
{
@@ -451,28 +432,34 @@ Encrypt a string using blowfish:
}
The ciphertext from the above example can be decrypted using the B<openssl>
-utility with the command line:
+utility with the command line (shown on two lines for clarity):
- S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d>
+ openssl idea -d <filename
+ -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
-General encryption, decryption function example using FILE I/O and RC2 with an
-80 bit key:
+General encryption and decryption function example using FILE I/O and AES128
+with a 128-bit key:
int do_crypt(FILE *in, FILE *out, int do_encrypt)
{
/* Allow enough space in output buffer for additional block */
- inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
+ unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
int inlen, outlen;
+ EVP_CIPHER_CTX ctx;
/* Bogus key and IV: we'd normally set these from
* another source.
*/
- unsigned char key[] = "0123456789";
- unsigned char iv[] = "12345678";
- /* Don't set key or IV because we will modify the parameters */
+ unsigned char key[] = "0123456789abcdeF";
+ unsigned char iv[] = "1234567887654321";
+
+ /* Don't set key or IV right away; we want to check lengths */
EVP_CIPHER_CTX_init(&ctx);
- EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
- EVP_CIPHER_CTX_set_key_length(&ctx, 10);
- /* We finished modifying parameters so now we can set key and IV */
+ EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
+ do_encrypt);
+ OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16);
+ OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16);
+
+ /* Now we can set key and IV */
EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
for(;;)
@@ -511,4 +498,7 @@ EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
OpenSSL 0.9.7.
+IDEA appeared in OpenSSL 0.9.7 but was often disabled due to
+patent concerns; the last patents expired in 2012.
+
=cut
diff --git a/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod b/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod
index 2db692e27..6f1017561 100644
--- a/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod
+++ b/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod
@@ -37,7 +37,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
B<NULL> if the key is not of the correct type.
-EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
however these use the supplied B<key> internally and so B<key>
will be freed when the parent B<pkey> is freed.
@@ -54,8 +54,8 @@ In accordance with the OpenSSL naming convention the key obtained
from or assigned to the B<pkey> using the B<1> functions must be
freed as well as B<pkey>.
-EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
-EVP_PKEY_assign_EC_KEY() are implemented as macros.
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+and EVP_PKEY_assign_EC_KEY() are implemented as macros.
=head1 RETURN VALUES
@@ -66,7 +66,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
an error occurred.
-EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
=head1 SEE ALSO
diff --git a/openssl/doc/crypto/EVP_PKEY_sign.pod b/openssl/doc/crypto/EVP_PKEY_sign.pod
index a044f2c13..21974b4b1 100644
--- a/openssl/doc/crypto/EVP_PKEY_sign.pod
+++ b/openssl/doc/crypto/EVP_PKEY_sign.pod
@@ -28,9 +28,14 @@ B<sig> and the amount of data written to B<siglen>.
=head1 NOTES
+EVP_PKEY_sign() does not hash the data to be signed, and therefore is
+normally used to sign digests. For signing arbitrary messages, see the
+L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)> and
+L<EVP_SignInit(3)|EVP_SignInit(3)> signing interfaces instead.
+
After the call to EVP_PKEY_sign_init() algorithm specific control
operations can be performed to set any appropriate parameters for the
-operation.
+operation (see L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>).
The function EVP_PKEY_sign() can be called more than once on the same
context if several operations are performed using the same parameters.
@@ -49,13 +54,17 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest:
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
+ /* md is a SHA-256 digest in this example. */
unsigned char *md, *sig;
- size_t mdlen, siglen;
+ size_t mdlen = 32, siglen;
EVP_PKEY *signing_key;
- /* NB: assumes signing_key, md and mdlen are already set up
- * and that signing_key is an RSA private key
+
+ /*
+ * NB: assumes signing_key and md are set up before the next
+ * step. signing_key must be an RSA private key and md must
+ * point to the SHA-256 digest to be signed.
*/
- ctx = EVP_PKEY_CTX_new(signing_key);
+ ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_sign_init(ctx) <= 0)
@@ -83,6 +92,7 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest:
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
+L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
diff --git a/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
index b34c68aba..7a27eef50 100644
--- a/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
+++ b/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
@@ -48,12 +48,13 @@ even if he gets hold of the normal (certified) key, as this key was
only used for signing.
In order to perform a DH key exchange the server must use a DH group
-(DH parameters) and generate a DH key. The server will always generate a new
-DH key during the negotiation, when the DH parameters are supplied via
-callback and/or when the SSL_OP_SINGLE_DH_USE option of
-L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set. It will
-immediately create a DH key, when DH parameters are supplied via
-SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. In this case,
+(DH parameters) and generate a DH key.
+The server will always generate a new DH key during the negotiation
+if either the DH parameters are supplied via callback or the
+SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set (or both).
+It will immediately create a DH key if DH parameters are supplied via
+SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set.
+In this case,
it may happen that a key is generated on initialization without later
being needed, while on the other hand the computer time during the
negotiation is being saved.
@@ -139,7 +140,7 @@ partly left out.)
dh_tmp = dh_512;
break;
case 1024:
- if (!dh_1024)
+ if (!dh_1024)
dh_1024 = get_dh1024();
dh_tmp = dh_1024;
break;