aboutsummaryrefslogtreecommitdiff
path: root/openssl/doc/crypto
diff options
context:
space:
mode:
Diffstat (limited to 'openssl/doc/crypto')
-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
7 files changed, 70 insertions, 66 deletions
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)>,