From ca3058f44f6c221a5580f274a8d643470f5ffa0a Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 3 Nov 2016 09:35:34 +0000 Subject: convert EVP manuals from pod to mdoc --- src/lib/libcrypto/doc/EVP_BytesToKey.pod | 68 --- src/lib/libcrypto/doc/EVP_DigestInit.pod | 277 ----------- src/lib/libcrypto/doc/EVP_DigestSignInit.pod | 85 ---- src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod | 80 --- src/lib/libcrypto/doc/EVP_EncryptInit.pod | 548 --------------------- src/lib/libcrypto/doc/EVP_OpenInit.pod | 61 --- src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod | 135 ----- src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod | 53 -- src/lib/libcrypto/doc/EVP_PKEY_cmp.pod | 62 --- src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod | 93 ---- src/lib/libcrypto/doc/EVP_PKEY_derive.pod | 94 ---- src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod | 93 ---- .../libcrypto/doc/EVP_PKEY_get_default_digest.pod | 41 -- src/lib/libcrypto/doc/EVP_PKEY_keygen.pod | 170 ------- src/lib/libcrypto/doc/EVP_PKEY_new.pod | 43 -- src/lib/libcrypto/doc/EVP_PKEY_print_private.pod | 54 -- src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod | 76 --- src/lib/libcrypto/doc/EVP_PKEY_sign.pod | 96 ---- src/lib/libcrypto/doc/EVP_PKEY_verify.pod | 92 ---- src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod | 105 ---- src/lib/libcrypto/doc/EVP_SealInit.pod | 82 --- src/lib/libcrypto/doc/EVP_SignInit.pod | 103 ---- src/lib/libcrypto/doc/EVP_VerifyInit.pod | 96 ---- src/lib/libcrypto/doc/evp.pod | 107 ---- 24 files changed, 2714 deletions(-) delete mode 100644 src/lib/libcrypto/doc/EVP_BytesToKey.pod delete mode 100644 src/lib/libcrypto/doc/EVP_DigestInit.pod delete mode 100644 src/lib/libcrypto/doc/EVP_DigestSignInit.pod delete mode 100644 src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod delete mode 100644 src/lib/libcrypto/doc/EVP_EncryptInit.pod delete mode 100644 src/lib/libcrypto/doc/EVP_OpenInit.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_cmp.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_derive.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_keygen.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_new.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_print_private.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_sign.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_verify.pod delete mode 100644 src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod delete mode 100644 src/lib/libcrypto/doc/EVP_SealInit.pod delete mode 100644 src/lib/libcrypto/doc/EVP_SignInit.pod delete mode 100644 src/lib/libcrypto/doc/EVP_VerifyInit.pod delete mode 100644 src/lib/libcrypto/doc/evp.pod (limited to 'src/lib/libcrypto/doc') diff --git a/src/lib/libcrypto/doc/EVP_BytesToKey.pod b/src/lib/libcrypto/doc/EVP_BytesToKey.pod deleted file mode 100644 index 2dffaa1efa..0000000000 --- a/src/lib/libcrypto/doc/EVP_BytesToKey.pod +++ /dev/null @@ -1,68 +0,0 @@ -=pod - -=head1 NAME - -EVP_BytesToKey - password based encryption routine - -=head1 SYNOPSIS - - #include - - int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md, - const unsigned char *salt, - const unsigned char *data, int datal, int count, - unsigned char *key,unsigned char *iv); - -=head1 DESCRIPTION - -EVP_BytesToKey() derives a key and IV from various parameters. B is -the cipher to derive the key and IV for. B is the message digest to use. -The B parameter is used as a salt in the derivation: it should point to -an 8 byte buffer or NULL if no salt is used. B is a buffer containing -B bytes which is used to derive the keying data. B is the -iteration count to use. The derived key and IV will be written to B -and B respectively. - -=head1 NOTES - -A typical application of this function is to derive keying material for an -encryption algorithm from a password in the B parameter. - -Increasing the B parameter slows down the algorithm which makes it -harder for an attacker to perform a brute force attack using a large number -of candidate passwords. - -If the total key and IV length is less than the digest length and -B is used then the derivation algorithm is compatible with PKCS#5 v1.5 -otherwise a non standard extension is used to derive the extra data. - -Newer applications should use more standard algorithms such as PBKDF2 as -defined in PKCS#5v2.1 for key derivation. - -=head1 KEY DERIVATION ALGORITHM - -The key and IV is derived by concatenating D_1, D_2, etc until -enough data is available for the key and IV. D_i is defined as: - - D_i = HASH^count(D_(i-1) || data || salt) - -where || denotes concatenation, D_0 is empty, HASH is the digest -algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) -is HASH(HASH(data)) and so on. - -The initial bytes are used for the key and the subsequent bytes for -the IV. - -=head1 RETURN VALUES - -EVP_BytesToKey() returns the size of the derived key in bytes. - -=head1 SEE ALSO - -L, L, -L, -L - -=head1 HISTORY - -=cut diff --git a/src/lib/libcrypto/doc/EVP_DigestInit.pod b/src/lib/libcrypto/doc/EVP_DigestInit.pod deleted file mode 100644 index c83dcc736f..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestInit.pod +++ /dev/null @@ -1,277 +0,0 @@ -=pod - -=head1 NAME - -EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, -EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, -EVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, -EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, -EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, -EVP_sha1, EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, -EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, -EVP_get_digestbyobj, EVP_DigestInit, EVP_DigestFinal - EVP digest routines - -=head1 SYNOPSIS - - #include - - void EVP_MD_CTX_init(EVP_MD_CTX *ctx); - EVP_MD_CTX *EVP_MD_CTX_create(void); - - int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); - int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); - int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, - unsigned int *s); - - 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_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); - - #define EVP_MAX_MD_SIZE 64 /* SHA512 */ - - int EVP_MD_type(const EVP_MD *md); - int EVP_MD_pkey_type(const EVP_MD *md); - int EVP_MD_size(const EVP_MD *md); - int EVP_MD_block_size(const EVP_MD *md); - - const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); - #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) - #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) - #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) - - const EVP_MD *EVP_md_null(void); - const EVP_MD *EVP_md2(void); - const EVP_MD *EVP_md5(void); - const EVP_MD *EVP_sha1(void); - const EVP_MD *EVP_dss(void); - const EVP_MD *EVP_dss1(void); - const EVP_MD *EVP_ripemd160(void); - - const EVP_MD *EVP_sha224(void); - const EVP_MD *EVP_sha256(void); - const EVP_MD *EVP_sha384(void); - const EVP_MD *EVP_sha512(void); - - const EVP_MD *EVP_get_digestbyname(const char *name); - #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) - #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) - -=head1 DESCRIPTION - -The EVP digest routines are a high level interface to message digests. - -EVP_MD_CTX_init() initializes digest context B. - -EVP_MD_CTX_create() allocates, initializes and returns a digest context. - -EVP_DigestInit_ex() sets up digest context B to use a digest -B from ENGINE B. B must be initialized before calling this -function. B will typically be supplied by a function such as EVP_sha1(). -If B is NULL then the default implementation of digest B is used. - -EVP_DigestUpdate() hashes B bytes of data at B into the -digest context B. This function can be called several times on the -same B to hash additional data. - -EVP_DigestFinal_ex() retrieves the digest value from B and places -it in B. If the B parameter is not NULL then the number of -bytes of data written (i.e. the length of the digest) will be written -to the integer at B, at most B bytes will be written. -After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() -can be made, but EVP_DigestInit_ex() can be called to initialize a new -digest operation. - -EVP_MD_CTX_cleanup() cleans up digest context B, it should be called -after a digest context is no longer needed. - -EVP_MD_CTX_destroy() cleans up digest context B and frees up the -space allocated to it, it should be called only on a context created -using EVP_MD_CTX_create(). - -EVP_MD_CTX_copy_ex() can be used to copy the message digest state from -B to B. This is useful if large amounts of data are to be -hashed which only differ in the last few bytes. B must be initialized -before calling this function. - -EVP_DigestInit() behaves in the same way as EVP_DigestInit_ex() except -the passed context B does not have to be initialized, and it always -uses the default digest implementation. - -EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest -context B is automatically cleaned up. - -EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination -B does not have to be initialized. - -EVP_MD_size() and EVP_MD_CTX_size() return the size of the message digest -when passed an B or an B structure, i.e. the size of the -hash. - -EVP_MD_block_size() and EVP_MD_CTX_block_size() return the block size of the -message digest when passed an B or an B structure. - -EVP_MD_type() and EVP_MD_CTX_type() return the NID of the OBJECT IDENTIFIER -representing the given message digest when passed an B structure. -For example EVP_MD_type(EVP_sha1()) returns B. This function is -normally used when setting ASN1 OIDs. - -EVP_MD_CTX_md() returns the B structure corresponding to the passed -B. - -EVP_MD_pkey_type() returns the NID of the public key signing algorithm -associated with this digest. For example EVP_sha1() is associated with RSA so -this will return B. Since digests and signature -algorithms are no longer linked this function is only retained for -compatibility reasons. - -EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(), EVP_sha384(), -EVP_sha512() and EVP_ripemd160() return B structures for the MD2, MD5, -SHA1, SHA224, SHA256, SHA384, SHA512 and RIPEMD160 digest algorithms -respectively. - -EVP_dss() and EVP_dss1() return B structures for SHA1 digest -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. - -EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it -returns is of zero length. - -EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() -return an B structure when passed a digest name, a digest NID or -an ASN1_OBJECT structure respectively. The digest table must be initialized -using, for example, OpenSSL_add_all_digests() for these functions to work. - -=head1 RETURN VALUES - -EVP_DigestInit_ex(), EVP_DigestUpdate() and EVP_DigestFinal_ex() return 1 for -success and 0 for failure. - -EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure. - -EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the -corresponding OBJECT IDENTIFIER or NID_undef if none exists. - -EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and -EVP_MD_CTX_block_size() return the digest or block size in bytes. - -EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), EVP_dss(), -EVP_dss1() and EVP_ripemd160() return pointers to the -corresponding EVP_MD structures. - -EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() -return either an B structure or NULL if an error occurs. - -=head1 NOTES - -The B 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. -The other digest algorithms are still in common use. - -For most applications the B 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 -obsolete but are retained to maintain compatibility with existing code. New -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. - -Stack allocation of EVP_MD_CTX structures is common, for example: - - EVP_MD_CTX mctx; - EVP_MD_CTX_init(&mctx); - -This will cause binary compatibility issues if the size of EVP_MD_CTX -structure changes (this will only happen with a major release of OpenSSL). -Applications wishing to avoid this should use EVP_MD_CTX_create() instead: - - EVP_MD_CTX *mctx; - mctx = EVP_MD_CTX_create(); - - -=head1 EXAMPLE - -This example digests the data "Test Message\n" and "Hello World\n", using the -digest name passed on the command line. - - #include - #include - - int - main(int argc, char *argv[]) - { - EVP_MD_CTX *mdctx; - const EVP_MD *md; - const char mess1[] = "Test Message\n"; - const char mess2[] = "Hello World\n"; - unsigned char md_value[EVP_MAX_MD_SIZE]; - int md_len, i; - - OpenSSL_add_all_digests(); - - if (argc <= 1) { - printf("Usage: mdtest digestname\n"); - exit(1); - } - - md = EVP_get_digestbyname(argv[1]); - if (md == NULL) { - printf("Unknown message digest %s\n", argv[1]); - exit(1); - } - - mdctx = EVP_MD_CTX_create(); - EVP_DigestInit_ex(mdctx, md, NULL); - EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); - EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); - EVP_DigestFinal_ex(mdctx, md_value, &md_len); - EVP_MD_CTX_destroy(mdctx); - - printf("Digest is: "); - for(i = 0; i < md_len; i++) - printf("%02x", md_value[i]); - printf("\n"); - } - -=head1 SEE ALSO - -L, L, L, -L, L, -L, L - -=head1 HISTORY - -EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), -EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() -and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7. - -EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), -EVP_dss(), EVP_dss1() 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 -use EVP_dss1() any more. - -OpenSSL 1.0 and later does not include the MD2 digest algorithm in the -default configuration due to its security weaknesses. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_DigestSignInit.pod b/src/lib/libcrypto/doc/EVP_DigestSignInit.pod deleted file mode 100644 index 00205d2ae9..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestSignInit.pod +++ /dev/null @@ -1,85 +0,0 @@ -=pod - -=head1 NAME - -EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing -functions - -=head1 SYNOPSIS - - #include - - int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, - const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); - int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); - int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); - -=head1 DESCRIPTION - -The EVP signature routines are a high level interface to digital signatures. - -EVP_DigestSignInit() sets up signing context B to use digest B from -ENGINE B and private key B. B must be initialized with -EVP_MD_CTX_init() before calling this function. If B is not NULL the -EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can -be used to set alternative signing options. - -EVP_DigestSignUpdate() hashes B bytes of data at B into the -signature context B. This function can be called several times on the -same B to include additional data. This function is currently implemented -using a macro. - -EVP_DigestSignFinal() signs the data in B places the signature in B. -If B is B then the maximum size of the output buffer is written to -the B parameter. If B is not B then before the call the -B parameter should contain the length of the B buffer, if the -call is successful the signature is written to B and the amount of data -written to B. - -=head1 RETURN VALUES - -EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() 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 error codes can be obtained from L. - -=head1 NOTES - -The B interface to digital signatures should almost always be used in -preference to the low level interfaces. This is because the code then becomes -transparent to the algorithm used and much more flexible. - -In previous versions of OpenSSL there was a link between message digest types -and public key algorithms. This meant that "clone" digests such as EVP_dss1() -needed to be used to sign using SHA1 and DSA. This is no longer necessary and -the use of clone digest is now discouraged. - -The call to EVP_DigestSignFinal() internally finalizes a copy of the digest -context. This means that calls to EVP_DigestSignUpdate() and -EVP_DigestSignFinal() can be called later to digest and sign additional data. - -Since only a copy of the digest context is ever finalized the context must -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -The use of EVP_PKEY_size() with these functions is discouraged because some -signature operations may have a signature length which depends on the -parameters set. As a result EVP_PKEY_size() would have to return a value -which indicates the maximum possible signature for any set of parameters. - -=head1 SEE ALSO - -L, -L, L, -L, L, L, -L, L, -L, L - -=head1 HISTORY - -EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() -were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod b/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod deleted file mode 100644 index 5dcfec1837..0000000000 --- a/src/lib/libcrypto/doc/EVP_DigestVerifyInit.pod +++ /dev/null @@ -1,80 +0,0 @@ -=pod - -=head1 NAME - -EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP -signature verification functions - -=head1 SYNOPSIS - - #include - - int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, - const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); - int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); - int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen); - -=head1 DESCRIPTION - -The EVP signature routines are a high level interface to digital signatures. - -EVP_DigestVerifyInit() sets up verification context B to use digest -B from ENGINE B and public key B. B must be initialized -with EVP_MD_CTX_init() before calling this function. If B is not NULL the -EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this -can be used to set alternative verification options. - -EVP_DigestVerifyUpdate() hashes B bytes of data at B into the -verification context B. This function can be called several times on the -same B to include additional data. This function is currently implemented -using a macro. - -EVP_DigestVerifyFinal() verifies the data in B against the signature in -B of length B. - -=head1 RETURN VALUES - -EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() 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. - -Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only -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. - -The error codes can be obtained from L. - -=head1 NOTES - -The B interface to digital signatures should almost always be used in -preference to the low level interfaces. This is because the code then becomes -transparent to the algorithm used and much more flexible. - -In previous versions of OpenSSL there was a link between message digest types -and public key algorithms. This meant that "clone" digests such as EVP_dss1() -needed to be used to sign using SHA1 and DSA. This is no longer necessary and -the use of clone digest is now discouraged. - -The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest -context. This means that calls to 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 -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -=head1 SEE ALSO - -L, -L, L, -L, L, L, -L, L, -L, L - -=head1 HISTORY - -EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() -were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_EncryptInit.pod b/src/lib/libcrypto/doc/EVP_EncryptInit.pod deleted file mode 100644 index 7ae3fe31ea..0000000000 --- a/src/lib/libcrypto/doc/EVP_EncryptInit.pod +++ /dev/null @@ -1,548 +0,0 @@ -=pod - -=head1 NAME - -EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate, -EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate, -EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate, -EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, -EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, -EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, -EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, -EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, -EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, -EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, -EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, -EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, -EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, -EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, -EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb, -EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb, -EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb, -EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc, -EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc, -EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, -EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, -EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, -EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, -EVP_aes_192_ccm, EVP_aes_256_ccm, EVP_rc5_32_12_16_cbc, -EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_ofb -- EVP cipher routines - -=head1 SYNOPSIS - - #include - - void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); - - int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - ENGINE *impl, unsigned char *key, unsigned char *iv); - int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - - int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - ENGINE *impl, unsigned char *key, unsigned char *iv); - int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - ENGINE *impl, unsigned char *key, unsigned char *iv, int enc); - int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv); - int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - - int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv); - int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char *key, unsigned char *iv, int enc); - int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, - int *outl); - - int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); - int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); - int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); - int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); - - const EVP_CIPHER *EVP_get_cipherbyname(const char *name); - #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) - #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) - - #define EVP_CIPHER_nid(e) ((e)->nid) - #define EVP_CIPHER_block_size(e) ((e)->block_size) - #define EVP_CIPHER_key_length(e) ((e)->key_len) - #define EVP_CIPHER_iv_length(e) ((e)->iv_len) - #define EVP_CIPHER_flags(e) ((e)->flags) - #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE) - int EVP_CIPHER_type(const EVP_CIPHER *ctx); - - #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) - #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) - #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) - #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len) - #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) - #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data) - #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d)) - #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) - #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags) - #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE) - - int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); - int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); - -=head1 DESCRIPTION - -The EVP cipher routines are a high level interface to certain -symmetric ciphers. - -EVP_CIPHER_CTX_init() initializes cipher context B. - -EVP_EncryptInit_ex() sets up cipher context B for encryption -with cipher B from ENGINE B. B must be initialized -before calling this function. B is normally supplied -by a function such as EVP_aes_256_cbc(). If B is NULL then the -default implementation is used. B is the symmetric key to use -and B is the IV to use (if necessary), the actual number of bytes -used for the key and IV depends on the cipher. It is possible to set -all parameters to NULL except B in an initial call and supply -the remaining parameters in subsequent calls, all of which have B -set to NULL. This is done when the default cipher parameters are not -appropriate. - -EVP_EncryptUpdate() encrypts B bytes from the buffer B and -writes the encrypted version to B. This function can be called -multiple times to encrypt successive blocks of data. The amount -of data written depends on the block alignment of the encrypted data: -as a result the amount of data written may be anything from zero bytes -to (inl + cipher_block_size - 1) so B should contain sufficient -room. The actual number of bytes written is placed in B. - -If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts -the "final" data, that is any data that remains in a partial block. -It uses L (aka PKCS padding). The encrypted -final data is written to B which should have sufficient space for -one cipher block. The number of bytes written is placed in B. After -this function is called the encryption operation is finished and no further -calls to EVP_EncryptUpdate() should be made. - -If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more -data and it will return an error if any data remains in a partial block: -that is if the total data length is not a multiple of the block size. - -EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the -corresponding decryption operations. EVP_DecryptFinal() will return an -error code if padding is enabled and the final block is not correctly -formatted. The parameters and restrictions are identical to the encryption -operations except that if padding is enabled the decrypted data buffer B -passed to EVP_DecryptUpdate() should have sufficient room for -(B + cipher_block_size) bytes unless the cipher block size is 1 in -which case B bytes is sufficient. - -EVP_CipherInit_ex(), EVP_CipherUpdate() and EVP_CipherFinal_ex() are -functions that can be used for decryption or encryption. The operation -performed depends on the value of the B parameter. It should be set -to 1 for encryption, 0 for decryption and -1 to leave the value unchanged -(the actual value of 'enc' being supplied in a previous call). - -EVP_CIPHER_CTX_cleanup() clears all information from a cipher context -and free up any allocated memory associate with it. It should be called -after all operations using a cipher are complete so sensitive information -does not remain in memory. - -EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a -similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and -EVP_CipherInit_ex() except the B parameter does not need to be -initialized and they always use the default cipher implementation. - -EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are -identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and -EVP_CipherFinal_ex(). In previous releases of OpenSSL they also used to clean -up the B, but this is no longer done and EVP_CIPHER_CTX_clean() -must be called to free any context resources. - -EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() -return an EVP_CIPHER structure when passed a cipher name, a NID or an -ASN1_OBJECT structure. - -EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when -passed an B or B structure. The actual NID -value is an internal value which may not have a corresponding OBJECT -IDENTIFIER. - -EVP_CIPHER_CTX_set_padding() enables or disables padding. By default -encryption operations are padded using standard block padding and the -padding is checked and removed when decrypting. If the B parameter -is zero then no padding is performed, the total amount of data encrypted -or decrypted must then be a multiple of the block size or an error will -occur. - -EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key -length of a cipher when passed an B or B -structure. The constant B is the maximum key length -for all ciphers. Note: although EVP_CIPHER_key_length() is fixed for a -given cipher, the value of EVP_CIPHER_CTX_key_length() may be different -for variable key length ciphers. - -EVP_CIPHER_CTX_set_key_length() sets the key length of the cipher ctx. -If the cipher is a fixed length cipher then attempting to set the key -length to any value other than the fixed value is an error. - -EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV -length of a cipher when passed an B or B. -It will return zero if the cipher does not use an IV. The constant -B is the maximum IV length for all ciphers. - -EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block -size of a cipher when passed an B or B -structure. The constant B is also the maximum block -length for all ciphers. - -EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed -cipher or context. This "type" is the actual NID of the cipher OBJECT -IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and -128 bit RC2 have the same NID. If the cipher does not have an object -identifier or does not have ASN1 support this function will return -B. - -EVP_CIPHER_CTX_cipher() returns the B structure when passed -an B structure. - -EVP_CIPHER_mode() and EVP_CIPHER_CTX_mode() return the block cipher mode: -EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE or -EVP_CIPH_OFB_MODE. If the cipher is a stream cipher then -EVP_CIPH_STREAM_CIPHER is returned. - -EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based -on the passed cipher. This will typically include any parameters and an -IV. The cipher IV (if any) must be set when this call is made. This call -should be made before the cipher is actually "used" (before any -EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function -may fail if the cipher does not have any ASN1 support. - -EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 -AlgorithmIdentifier "parameter". The precise effect depends on the cipher -In the case of RC2, for example, it will set the IV and effective key length. -This function should be called after the base cipher type is set but before -the key is set. For example EVP_CipherInit() will be called with the IV and -key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally -EVP_CipherInit() again with all parameters except the key set to NULL. It is -possible for this function to fail if the cipher does not have any ASN1 support -or the parameters cannot be set (for example the RC2 effective key length -is not supported. - -EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined -and set. Currently only the RC2 effective key length and the number of rounds of -RC5 can be set. - -=head1 RETURN VALUES - -EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() -return 1 for success and 0 for failure. - -EVP_DecryptInit_ex() and EVP_DecryptUpdate() return 1 for success and 0 for -failure. EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for -success. - -EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for -failure. EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for -success. - -EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure. - -EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() -return an B structure or NULL on error. - -EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. - -EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block -size. - -EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key -length. - -EVP_CIPHER_CTX_set_padding() always returns 1. - -EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV -length or zero if the cipher does not use an IV. - -EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the NID of the cipher's -OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. - -EVP_CIPHER_CTX_cipher() returns an B structure. - -EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for -success or zero for failure. - -=head1 CIPHER LISTING - -All algorithms have a fixed key length unless otherwise stated. - -=over 4 - -=item EVP_enc_null(void) - -Null cipher: does nothing. - -=item EVP_aes_128_cbc(void), EVP_aes_128_ecb(void), EVP_aes_128_cfb(void), EVP_aes_128_ofb(void) - -128-bit AES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_aes_192_cbc(void), EVP_aes_192_ecb(void), EVP_aes_192_cfb(void), EVP_aes_192_ofb(void) - -192-bit AES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_aes_256_cbc(void), EVP_aes_256_ecb(void), EVP_aes_256_cfb(void), EVP_aes_256_ofb(void) - -256-bit AES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) - -DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), -EVP_des_ede_cfb(void) - -Two key triple DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), -EVP_des_ede3_cfb(void) - -Three key triple DES in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_desx_cbc(void) - -DESX algorithm in CBC mode. - -=item EVP_rc4(void) - -RC4 stream cipher. This is a variable key length cipher with default key length -128 bits. - -=item EVP_rc4_40(void) - -RC4 stream cipher with 40 bit key length. This is obsolete and new code should -use EVP_rc4() and the EVP_CIPHER_CTX_set_key_length() function. - -=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), -EVP_idea_ofb(void), EVP_idea_cbc(void) - -IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. - -=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) - -RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a -variable key length cipher with an additional parameter called "effective key -bits" or "effective key length". By default both are set to 128 bits. - -=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void) - -RC2 algorithm in CBC mode with a default key length and effective key length of -40 and 64 bits. These are obsolete and new code should use EVP_rc2_cbc(), -EVP_CIPHER_CTX_set_key_length() and EVP_CIPHER_CTX_ctrl() to set the key length -and effective key length. - -=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); - -Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This -is a variable key length cipher. - -=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), -EVP_cast5_ofb(void) - -CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is -a variable key length cipher. - -=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), -EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) - -RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a -variable key length cipher with an additional "number of rounds" parameter. By -default the key length is set to 128 bits and 12 rounds. - -=back - -=head1 NOTES - -Where possible the B interface to symmetric ciphers should be used in -preference to the low level interfaces. This is because the code then becomes -transparent to the cipher used and much more flexible. - -PKCS padding works by adding B padding bytes of value B to make the total -length of the encrypted data a multiple of the block size. Padding is always -added so if the data is already a multiple of the block size B will equal -the block size. For example if the block size is 8 and 11 bytes are to be -encrypted then 5 padding bytes of value 5 will be added. - -When decrypting the final block is checked to see if it has the correct form. - -Although the decryption operation can produce an error if padding is enabled, -it is not a strong test that the input data or key is correct. A random block -has better than 1 in 256 chance of being of the correct format and problems with -the input data earlier on will not produce a final decrypt error. - -If padding is disabled then the decryption operation will always succeed if -the total amount of data decrypted is a multiple of the block size. - -The functions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), -EVP_CipherInit() and EVP_CipherFinal() are obsolete but are retained for -compatibility with existing code. New code should use EVP_EncryptInit_ex(), -EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), -EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an -existing context without allocating and freeing it up on each call. - -=head1 BUGS - -For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is -a limitation of the current RC5 code rather than the EVP interface. - -EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with -default key lengths. If custom ciphers exceed these values the results are -unpredictable. This is because it has become standard practice to define a -generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes. - -The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested -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: - - int - do_crypt(char *outfile) - { - unsigned char outbuf[1024]; - int outlen, tmplen; - /* - * Bogus key and IV: we'd normally set these from - * another source. - */ - unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; - unsigned char iv[] = {1,2,3,4,5,6,7,8}; - const 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); - - if (!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, - strlen(intext))) { - /* Error */ - return 0; - } - /* - * Buffer passed to EVP_EncryptFinal() must be after data just - * encrypted to avoid overwriting it. - */ - if (!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) { - /* Error */ - return 0; - } - outlen += tmplen; - EVP_CIPHER_CTX_cleanup(&ctx); - /* - * Need binary mode for fopen because encrypted data is - * binary data. Also cannot use strlen() on it because - * it won't be NUL terminated and may contain embedded - * NULs. - */ - out = fopen(outfile, "wb"); - fwrite(outbuf, 1, outlen, out); - fclose(out); - return 1; - } - -The ciphertext from the above example can be decrypted using the B -utility with the command line: - - S - -General encryption, decryption function example using FILE I/O and RC2 with an -80 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]; - int inlen, outlen; - /* - * 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 */ - 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, NULL, NULL, key, iv, do_encrypt); - - for(;;) { - inlen = fread(inbuf, 1, 1024, in); - if (inlen <= 0) - break; - if (!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, - inlen)) { - /* Error */ - EVP_CIPHER_CTX_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - } - if (!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) { - /* Error */ - EVP_CIPHER_CTX_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - - EVP_CIPHER_CTX_cleanup(&ctx); - return 1; - } - -=head1 SEE ALSO - -L - -=head1 HISTORY - -EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), -EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), -EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in -OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_OpenInit.pod b/src/lib/libcrypto/doc/EVP_OpenInit.pod deleted file mode 100644 index 0242f66715..0000000000 --- a/src/lib/libcrypto/doc/EVP_OpenInit.pod +++ /dev/null @@ -1,61 +0,0 @@ -=pod - -=head1 NAME - -EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption - -=head1 SYNOPSIS - - #include - - int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, - int ekl,unsigned char *iv,EVP_PKEY *priv); - int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - -=head1 DESCRIPTION - -The EVP envelope routines are a high level interface to envelope -decryption. They decrypt a public key encrypted symmetric key and -then decrypt data using it. - -EVP_OpenInit() initializes a cipher context B for decryption -with cipher B. It decrypts the encrypted symmetric key of length -B bytes passed in the B parameter using the private key B. -The IV is supplied in the B parameter. - -EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties -as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as -documented on the L manual -page. - -=head1 NOTES - -It is possible to call EVP_OpenInit() twice in the same way as -EVP_DecryptInit(). The first call should have B set to NULL -and (after setting any cipher parameters) it should be called again -with B set to NULL. - -If the cipher passed in the B parameter is a variable length -cipher then the key length will be set to the value of the recovered -key length. If the cipher is a fixed length cipher then the recovered -key length must match the fixed cipher length. - -=head1 RETURN VALUES - -EVP_OpenInit() returns 0 on error or a non zero integer (actually the -recovered secret key size) if successful. - -EVP_OpenUpdate() returns 1 for success or 0 for failure. - -EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success. - -=head1 SEE ALSO - -L, L, -L, -L - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod deleted file mode 100644 index e8776e1e67..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_CTX_ctrl.pod +++ /dev/null @@ -1,135 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_get_default_digest_nid, -EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding, -EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits, -EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits, -EVP_PKEY_CTX_set_dh_paramgen_prime_len, -EVP_PKEY_CTX_set_dh_paramgen_generator, -EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, - int cmd, int p1, void *p2); - int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, - const char *value); - - int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); - - #include - - int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md); - - int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad); - int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len); - int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits); - int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp); - - #include - int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits); - - #include - int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len); - int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen); - - #include - int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); - -=head1 DESCRIPTION - -The function EVP_PKEY_CTX_ctrl() sends a control operation to the context -B. The key type used must match B if it is not -1. The parameter -B is a mask indicating which operations the control can be applied to. -The control command is indicated in B and any additional arguments in -B and B. - -Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will -instead call one of the algorithm specific macros below. - -The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm -specific control operation to a context B in string form. This is -intended to be used for options specified on the command line or in text -files. The commands supported are documented in the openssl utility -command line pages for the option B<-pkeyopt> which is supported by the -B, B and B commands. - -All the remaining "functions" are implemented as macros. - -The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used -in a signature. It can be used with any public key algorithm supporting -signature operations. - -The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B. -The B parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, -RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, -RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), -RSA_X931_PADDING for X9.31 padding (signature operations only) and -RSA_PKCS1_PSS_PADDING (sign and verify only). - -Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() is -used. If this macro is called for PKCS#1 padding the plaintext buffer is an -actual digest value and is encapsulated in a DigestInfo structure according to -PKCS#1 when signing and this structure is expected (and stripped off) when -verifying. If this control is not used with RSA and PKCS#1 padding then the -supplied data is used directly and not encapsulated. In the case of X9.31 -padding for RSA the algorithm identifier byte is added or checked and removed -if this control is called. If it is not called then the first byte of the -plaintext buffer is expected to be the algorithm identifier byte. - -The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to -B as its name implies it is only supported for PSS padding. Two special -values are supported: -1 sets the salt length to the digest length. When -signing -2 sets the salt length to the maximum permissible value. When -verifying -2 causes the salt length to be automatically determined based on the -B block structure. If this macro is not called a salt length value of -2 -is used by default. - -The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for -RSA key generation to B. If not specified 1024 bits is used. - -The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value -for RSA key generation to B currently it should be an odd integer. The -B pointer is used internally by this function so it should not be -modified or free after the call. If this macro is not called then 65537 is used. - -The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used -for DSA parameter generation to B. If not specified 1024 is used. - -The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH -prime parameter B

for DH parameter generation. If this macro is not called -then 1024 is used. - -The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B -for DH parameter generation. If not specified 2 is used. - -The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter -generation to B. For EC parameter generation this macro must be called -or an error occurs because there is no default curve. - -=head1 RETURN VALUES - -EVP_PKEY_CTX_ctrl() and its macros return a positive value 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. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod b/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod deleted file mode 100644 index 60ad61e853..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_CTX_new.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - -public key algorithm context functions. - -=head1 SYNOPSIS - - #include - - EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e); - EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e); - EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx); - void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx); - -=head1 DESCRIPTION - -The EVP_PKEY_CTX_new() function allocates public key algorithm context using -the algorithm specified in B and ENGINE B. - -The EVP_PKEY_CTX_new_id() function allocates public key algorithm context -using the algorithm specified by B and ENGINE B. It is normally used -when no B structure is associated with the operations, for example -during parameter generation of key generation for some algorithms. - -EVP_PKEY_CTX_dup() duplicates the context B. - -EVP_PKEY_CTX_free() frees up the context B. - -=head1 NOTES - -The B structure is an opaque public key algorithm context used -by the OpenSSL high level public key API. Contexts B be shared between -threads: that is it is not permissible to use the same context simultaneously -in two threads. - -=head1 RETURN VALUES - -EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() returns either -the newly allocated B structure of B if an error occurred. - -EVP_PKEY_CTX_free() does not return a value. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod b/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod deleted file mode 100644 index 7a690247bf..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_cmp.pod +++ /dev/null @@ -1,62 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, -EVP_PKEY_cmp - public key parameter and comparison functions - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_missing_parameters(const EVP_PKEY *pkey); - int EVP_PKEY_copy_parameters(EVP_PKEY *to, const EVP_PKEY *from); - - int EVP_PKEY_cmp_parameters(const EVP_PKEY *a, const EVP_PKEY *b); - int EVP_PKEY_cmp(const EVP_PKEY *a, const EVP_PKEY *b); - -=head1 DESCRIPTION - -The function EVP_PKEY_missing_parameters() returns 1 if the public key -parameters of B are missing and 0 if they are present or the algorithm -doesn't use parameters. - -The function EVP_PKEY_copy_parameters() copies the parameters from key -B to key B. - -The function EVP_PKEY_cmp_parameters() compares the parameters of keys -B and B. - -The function EVP_PKEY_cmp() compares the public key components and parameters -(if present) of keys B and B. - -=head1 NOTES - -The main purpose of the functions EVP_PKEY_missing_parameters() and -EVP_PKEY_copy_parameters() is to handle public keys in certificates where the -parameters are sometimes omitted from a public key if they are inherited from -the CA that signed it. - -Since OpenSSL private keys contain public key components too the function -EVP_PKEY_cmp() can also be used to determine if a private key matches -a public key. - -=head1 RETURN VALUES - -The function EVP_PKEY_missing_parameters() returns 1 if the public key -parameters of B are missing and 0 if they are present or the algorithm -doesn't use parameters. - -These functions EVP_PKEY_copy_parameters() returns 1 for success and 0 for -failure. - -The function EVP_PKEY_cmp_parameters() and EVP_PKEY_cmp() return 1 if the -keys match, 0 if they don't match, -1 if the key types are different and --2 if the operation is not supported. - -=head1 SEE ALSO - -L, -L - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod deleted file mode 100644 index a64ef12866..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_decrypt.pod +++ /dev/null @@ -1,93 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, - unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); - -=head1 DESCRIPTION - -The EVP_PKEY_decrypt_init() function initializes a public key algorithm -context using key B for a decryption operation. - -The EVP_PKEY_decrypt() function performs a public key decryption operation -using B. The data to be decrypted is specified using the B and -B parameters. If B is B then the maximum size of the output -buffer is written to the B parameter. If B is not B then -before the call the B parameter should contain the length of the -B buffer, if the call is successful the decrypted data is written to -B and the amount of data written to B. - -=head1 NOTES - -After the call to EVP_PKEY_decrypt_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_decrypt() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() 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. - -=head1 EXAMPLE - -Decrypt data using OAEP (for RSA keys): - - #include - #include - - EVP_PKEY_CTX *ctx; - unsigned char *out, *in; - size_t outlen, inlen; - EVP_PKEY *key; - /* NB: assumes key in, inlen are already set up - * and that key is an RSA private key - */ - ctx = EVP_PKEY_CTX_new(key); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_decrypt_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0) - /* Error */ - - out = malloc(outlen); - - if (!out) - /* malloc failure */ - - if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0) - /* Error */ - - /* Decrypted data is outlen bytes written to buffer out */ - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_derive.pod b/src/lib/libcrypto/doc/EVP_PKEY_derive.pod deleted file mode 100644 index 09654e1b81..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_derive.pod +++ /dev/null @@ -1,94 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public -key algorithm shared secret. - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer); - int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); - -=head1 DESCRIPTION - -The EVP_PKEY_derive_init() function initializes a public key algorithm -context using key B for shared secret derivation. - -The EVP_PKEY_derive_set_peer() function sets the peer key: this will normally -be a public key. - -The EVP_PKEY_derive() derives a shared secret using B. -If B is B then the maximum size of the output buffer is written to -the B parameter. If B is not B then before the call the -B parameter should contain the length of the B buffer, if the call -is successful the shared secret is written to B and the amount of data -written to B. - -=head1 NOTES - -After the call to EVP_PKEY_derive_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_derive() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_derive_init() and EVP_PKEY_derive() 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. - -=head1 EXAMPLE - -Derive shared secret (for example DH or EC keys): - - #include - #include - - EVP_PKEY_CTX *ctx; - unsigned char *skey; - size_t skeylen; - EVP_PKEY *pkey, *peerkey; - /* NB: assumes pkey, peerkey have been already set up */ - - ctx = EVP_PKEY_CTX_new(pkey); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_derive_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) - /* Error */ - - skey = malloc(skeylen); - - if (!skey) - /* malloc failure */ - - if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) - /* Error */ - - /* Shared secret is skey bytes written to buffer skey */ - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod b/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod deleted file mode 100644 index b3ca123df0..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_encrypt.pod +++ /dev/null @@ -1,93 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, - unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); - -=head1 DESCRIPTION - -The EVP_PKEY_encrypt_init() function initializes a public key algorithm -context using key B for an encryption operation. - -The EVP_PKEY_encrypt() function performs a public key encryption operation -using B. The data to be encrypted is specified using the B and -B parameters. If B is B then the maximum size of the output -buffer is written to the B parameter. If B is not B then -before the call the B parameter should contain the length of the -B buffer, if the call is successful the encrypted data is written to -B and the amount of data written to B. - -=head1 NOTES - -After the call to EVP_PKEY_encrypt_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_encrypt() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() 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. - -=head1 EXAMPLE - -Encrypt data using OAEP (for RSA keys): - - #include - #include - - EVP_PKEY_CTX *ctx; - unsigned char *out, *in; - size_t outlen, inlen; - EVP_PKEY *key; - /* NB: assumes key in, inlen are already set up - * and that key is an RSA public key - */ - ctx = EVP_PKEY_CTX_new(key); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_encrypt_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_OAEP_PADDING) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0) - /* Error */ - - out = malloc(outlen); - - if (!out) - /* malloc failure */ - - if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0) - /* Error */ - - /* Encrypted data is outlen bytes written to buffer out */ - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod b/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod deleted file mode 100644 index 8ff597d44a..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_get_default_digest.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_get_default_digest_nid - get default signature digest - -=head1 SYNOPSIS - - #include - int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); - -=head1 DESCRIPTION - -The EVP_PKEY_get_default_digest_nid() function sets B to the default -message digest NID for the public key signature operations associated with key -B. - -=head1 NOTES - -For all current standard OpenSSL public key algorithms SHA1 is returned. - -=head1 RETURN VALUES - -The EVP_PKEY_get_default_digest_nid() function returns 1 if the message digest -is advisory (that is other digests can be used) and 2 if it is mandatory (other -digests can not be used). It returns 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. - -=head1 SEE ALSO - -L, -L, -L, -L, - -=head1 HISTORY - -This function was first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod b/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod deleted file mode 100644 index adcf3560e0..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_keygen.pod +++ /dev/null @@ -1,170 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, -EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, -EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, -EVP_PKEY_CTX_get_app_data - key and parameter generation functions - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); - int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey); - - typedef int EVP_PKEY_gen_cb(EVP_PKEY_CTX *ctx); - - void EVP_PKEY_CTX_set_cb(EVP_PKEY_CTX *ctx, EVP_PKEY_gen_cb *cb); - EVP_PKEY_gen_cb *EVP_PKEY_CTX_get_cb(EVP_PKEY_CTX *ctx); - - int EVP_PKEY_CTX_get_keygen_info(EVP_PKEY_CTX *ctx, int idx); - - void EVP_PKEY_CTX_set_app_data(EVP_PKEY_CTX *ctx, void *data); - void *EVP_PKEY_CTX_get_app_data(EVP_PKEY_CTX *ctx); - -=head1 DESCRIPTION - -The EVP_PKEY_keygen_init() function initializes a public key algorithm -context using key B for a key generation operation. - -The EVP_PKEY_keygen() function performs a key generation operation, the -generated key is written to B. - -The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar -except parameters are generated. - -The function EVP_PKEY_set_cb() sets the key or parameter generation callback -to B. The function EVP_PKEY_CTX_get_cb() returns the key or parameter -generation callback. - -The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated -with the generation operation. If B is -1 the total number of -parameters available is returned. Any non negative value returns the value of -that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for -B should only be called within the generation callback. - -If the callback returns 0 then the key generation operation is aborted and an -error occurs. This might occur during a time consuming operation where -a user clicks on a "cancel" button. - -The functions EVP_PKEY_CTX_set_app_data() and EVP_PKEY_CTX_get_app_data() set -and retrieve an opaque pointer. This can be used to set some application -defined value which can be retrieved in the callback: for example a handle -which is used to update a "progress dialog". - -=head1 NOTES - -After the call to EVP_PKEY_keygen_init() or EVP_PKEY_paramgen_init() algorithm -specific control operations can be performed to set any appropriate parameters -for the operation. - -The functions EVP_PKEY_keygen() and EVP_PKEY_paramgen() can be called more than -once on the same context if several operations are performed using the same -parameters. - -The meaning of the parameters passed to the callback will depend on the -algorithm and the specific implementation of the algorithm. Some might not -give any useful information at all during key or parameter generation. Others -might not even call the callback. - -The operation performed by key or parameter generation depends on the algorithm -used. In some cases (e.g. EC with a supplied named curve) the "generation" -option merely sets the appropriate fields in an EVP_PKEY structure. - -In OpenSSL an EVP_PKEY structure containing a private key also contains the -public key components and parameters (if any). An OpenSSL private key is -equivalent to what some libraries call a "key pair". A private key can be used -in functions which require the use of a public key or parameters. - -=head1 RETURN VALUES - -EVP_PKEY_keygen_init(), EVP_PKEY_paramgen_init(), EVP_PKEY_keygen() and -EVP_PKEY_paramgen() 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. - -=head1 EXAMPLES - -Generate a 2048 bit RSA key: - - #include - #include - - EVP_PKEY_CTX *ctx; - EVP_PKEY *pkey = NULL; - ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_keygen_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) - /* Error */ - - /* Generate key */ - if (EVP_PKEY_keygen(ctx, &pkey) <= 0) - /* Error */ - -Generate a key from a set of parameters: - - #include - #include - - EVP_PKEY_CTX *ctx; - EVP_PKEY *pkey = NULL, *param; - /* Assumed param is set up already */ - ctx = EVP_PKEY_CTX_new(param); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_keygen_init(ctx) <= 0) - /* Error */ - - /* Generate key */ - if (EVP_PKEY_keygen(ctx, &pkey) <= 0) - /* Error */ - -Example of generation callback for OpenSSL public key implementations: - - /* Application data is a BIO to output status to */ - - EVP_PKEY_CTX_set_app_data(ctx, status_bio); - - static int - genpkey_cb(EVP_PKEY_CTX *ctx) - { - char c = '*'; - BIO *b = EVP_PKEY_CTX_get_app_data(ctx); - int p; - - p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); - if (p == 0) - c='.'; - if (p == 1) - c='+'; - if (p == 2) - c='*'; - if (p == 3) - c='\n'; - BIO_write(b,&c,1); - (void)BIO_flush(b); - return 1; - } - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_new.pod b/src/lib/libcrypto/doc/EVP_PKEY_new.pod deleted file mode 100644 index 7792714659..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_new.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_new, EVP_PKEY_free - private key allocation functions. - -=head1 SYNOPSIS - - #include - - EVP_PKEY *EVP_PKEY_new(void); - void EVP_PKEY_free(EVP_PKEY *key); - - -=head1 DESCRIPTION - -The EVP_PKEY_new() function allocates an empty B -structure which is used by OpenSSL to store private keys. - -EVP_PKEY_free() frees up the private key B. - -=head1 NOTES - -The B structure is used by various OpenSSL functions -which require a general private key without reference to any -particular algorithm. - -The structure returned by EVP_PKEY_new() is empty. To add a -private key to this empty structure the functions described in -L should be used. - -=head1 RETURN VALUES - -EVP_PKEY_new() returns either the newly allocated B -structure of B if an error occurred. - -EVP_PKEY_free() does not return a value. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod b/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod deleted file mode 100644 index eabbaed264..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_print_private.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public -key algorithm printing routines. - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); - int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); - int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); - -=head1 DESCRIPTION - -The functions EVP_PKEY_print_public(), EVP_PKEY_print_private() and -EVP_PKEY_print_params() print out the public, private or parameter components -of key B respectively. The key is sent to BIO B in human readable -form. The parameter B indicated how far the printout should be indented. - -The B parameter allows the print output to be finely tuned by using -ASN1 printing options. If B is set to NULL then default values will -be used. - -=head1 NOTES - -Currently no public key algorithms include any options in the B parameter -parameter. - -If the key does not include all the components indicated by the function then -only those contained in the key will be printed. For example passing a public -key to EVP_PKEY_print_private() will only print the public components. - -=head1 RETURN VALUES - -These functions all 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. - -=head1 SEE ALSO - -L, -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod b/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod deleted file mode 100644 index 096e969fa3..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_set1_RSA.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, -EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, -EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, -EVP_PKEY_assign_EC_KEY, EVP_PKEY_type - EVP_PKEY assignment functions. - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key); - int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key); - int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key); - int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); - - RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); - DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); - DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); - EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); - - int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key); - int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key); - int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key); - int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); - - int EVP_PKEY_type(int type); - -=head1 DESCRIPTION - -EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and -EVP_PKEY_set1_EC_KEY() set the key referenced by B to B. - -EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and -EVP_PKEY_get1_EC_KEY() return the referenced key in B or -B if the key is not of the correct type. - -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 -however these use the supplied B internally and so B -will be freed when the parent B is freed. - -EVP_PKEY_type() returns the type of key corresponding to the value -B. The type of a key can be obtained with -EVP_PKEY_type(pkey->type). The return value will be EVP_PKEY_RSA, -EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding -key types or NID_undef if the key type is unassigned. - -=head1 NOTES - -In accordance with the OpenSSL naming convention the key obtained -from or assigned to the B using the B<1> functions must be -freed as well as B. - -EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() -EVP_PKEY_assign_EC_KEY() are implemented as macros. - -=head1 RETURN VALUES - -EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and -EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure. - -EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and -EVP_PKEY_get1_EC_KEY() return the referenced key or B if -an error occurred. - -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 - -L - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_sign.pod b/src/lib/libcrypto/doc/EVP_PKEY_sign.pod deleted file mode 100644 index 1925706d96..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_sign.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, - unsigned char *sig, size_t *siglen, - const unsigned char *tbs, size_t tbslen); - -=head1 DESCRIPTION - -The EVP_PKEY_sign_init() function initializes a public key algorithm -context using key B for a signing operation. - -The EVP_PKEY_sign() function performs a public key signing operation -using B. The data to be signed is specified using the B and -B parameters. If B is B then the maximum size of the output -buffer is written to the B parameter. If B is not B then -before the call the B parameter should contain the length of the -B buffer, if the call is successful the signature is written to -B and the amount of data written to B. - -=head1 NOTES - -After the call to EVP_PKEY_sign_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_sign() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_sign_init() and EVP_PKEY_sign() 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. - -=head1 EXAMPLE - -Sign data using RSA with PKCS#1 padding and SHA256 digest: - - #include - #include - - EVP_PKEY_CTX *ctx; - unsigned char *md, *sig; - size_t mdlen, 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 - */ - ctx = EVP_PKEY_CTX_new(signing_key); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_sign_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) - /* Error */ - - sig = malloc(siglen); - - if (!sig) - /* malloc failure */ - - if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) - /* Error */ - - /* Signature is siglen bytes written to buffer sig */ - - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_verify.pod b/src/lib/libcrypto/doc/EVP_PKEY_verify.pod deleted file mode 100644 index 0f092ca8e1..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_verify.pod +++ /dev/null @@ -1,92 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public -key algorithm - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, - const unsigned char *sig, size_t siglen, - const unsigned char *tbs, size_t tbslen); - -=head1 DESCRIPTION - -The EVP_PKEY_verify_init() function initializes a public key algorithm -context using key B for a signature verification operation. - -The EVP_PKEY_verify() function performs a public key verification operation -using B. The signature is specified using the B and -B parameters. The verified data (i.e. the data believed originally -signed) is specified using the B and B parameters. - -=head1 NOTES - -After the call to EVP_PKEY_verify_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_verify() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_verify_init() and EVP_PKEY_verify() return 1 if the verification was -successful and 0 if it failed. Unlike other functions the return value 0 from -EVP_PKEY_verify() only 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. - -A negative value indicates an error other that signature verification failure. -In particular a return value of -2 indicates the operation is not supported by -the public key algorithm. - -=head1 EXAMPLE - -Verify signature using PKCS#1 and SHA256 digest: - - #include - #include - - EVP_PKEY_CTX *ctx; - unsigned char *md, *sig; - size_t mdlen, siglen; - EVP_PKEY *verify_key; - /* NB: assumes verify_key, sig, siglen md and mdlen are already set up - * and that verify_key is an RSA public key - */ - ctx = EVP_PKEY_CTX_new(verify_key); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_verify_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ - - /* Perform operation */ - ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); - - /* ret == 1 indicates success, 0 verify failure and < 0 for some - * other error. - */ - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod b/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod deleted file mode 100644 index 095e53ea2f..0000000000 --- a/src/lib/libcrypto/doc/EVP_PKEY_verify_recover.pod +++ /dev/null @@ -1,105 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using -a public key algorithm - -=head1 SYNOPSIS - - #include - - int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); - int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, - unsigned char *rout, size_t *routlen, - const unsigned char *sig, size_t siglen); - -=head1 DESCRIPTION - -The EVP_PKEY_verify_recover_init() function initializes a public key algorithm -context using key B for a verify recover operation. - -The EVP_PKEY_verify_recover() function recovers signed data -using B. The signature is specified using the B and -B parameters. If B is B then the maximum size of the output -buffer is written to the B parameter. If B is not B then -before the call the B parameter should contain the length of the -B buffer, if the call is successful recovered data is written to -B and the amount of data written to B. - -=head1 NOTES - -Normally an application is only interested in whether a signature verification -operation is successful in those cases the EVP_verify() function should be -used. - -Sometimes however it is useful to obtain the data originally signed using a -signing operation. Only certain public key algorithms can recover a signature -in this way (for example RSA in PKCS padding mode). - -After the call to EVP_PKEY_verify_recover_init() algorithm specific control -operations can be performed to set any appropriate parameters for the -operation. - -The function EVP_PKEY_verify_recover() can be called more than once on the same -context if several operations are performed using the same parameters. - -=head1 RETURN VALUES - -EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() 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. - -=head1 EXAMPLE - -Recover digest originally signed using PKCS#1 and SHA256 digest: - - #include - #include - - EVP_PKEY_CTX *ctx; - unsigned char *rout, *sig; - size_t routlen, siglen; - EVP_PKEY *verify_key; - /* NB: assumes verify_key, sig and siglen are already set up - * and that verify_key is an RSA public key - */ - ctx = EVP_PKEY_CTX_new(verify_key); - if (!ctx) - /* Error occurred */ - if (EVP_PKEY_verify_recover_init(ctx) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ - if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ - - /* Determine buffer length */ - if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0) - /* Error */ - - rout = malloc(routlen); - - if (!rout) - /* malloc failure */ - - if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0) - /* Error */ - - /* Recovered data is routlen bytes written to buffer rout */ - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L - -=head1 HISTORY - -These functions were first added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_SealInit.pod b/src/lib/libcrypto/doc/EVP_SealInit.pod deleted file mode 100644 index 76eebb72a9..0000000000 --- a/src/lib/libcrypto/doc/EVP_SealInit.pod +++ /dev/null @@ -1,82 +0,0 @@ -=pod - -=head1 NAME - -EVP_SealInit, EVP_SealUpdate, EVP_SealFinal - EVP envelope encryption - -=head1 SYNOPSIS - - #include - - int EVP_SealInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, - unsigned char **ek, int *ekl, unsigned char *iv, - EVP_PKEY **pubk, int npubk); - int EVP_SealUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl, unsigned char *in, int inl); - int EVP_SealFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, - int *outl); - -=head1 DESCRIPTION - -The EVP envelope routines are a high level interface to envelope -encryption. They generate a random key and IV (if required) then -"envelope" it by using public key encryption. Data can then be -encrypted using this key. - -EVP_SealInit() initializes a cipher context B for encryption -with cipher B using a random secret key and IV. B is normally -supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted -using one or more public keys, this allows the same encrypted data to be -decrypted using any of the corresponding private keys. B is an array of -buffers where the public key encrypted secret key will be written, each buffer -must contain enough room for the corresponding encrypted key: that is -B must have room for B bytes. The actual -size of each encrypted secret key is written to the array B. B is -an array of B public keys. - -The B parameter is a buffer where the generated IV is written to. It must -contain enough room for the corresponding cipher's IV, as determined by (for -example) EVP_CIPHER_iv_length(type). - -If the cipher does not require an IV then the B parameter is ignored -and can be B. - -EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties -as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as -documented on the L manual -page. - -=head1 RETURN VALUES - -EVP_SealInit() returns 0 on error or B if successful. - -EVP_SealUpdate() and EVP_SealFinal() return 1 for success and 0 for -failure. - -=head1 NOTES - -The public key must be RSA because it is the only OpenSSL public key -algorithm that supports key transport. - -Envelope encryption is the usual method of using public key encryption -on large amounts of data, this is because public key encryption is slow -but symmetric encryption is fast. So symmetric encryption is used for -bulk encryption and the small random symmetric key used is transferred -using public key encryption. - -It is possible to call EVP_SealInit() twice in the same way as -EVP_EncryptInit(). The first call should have B set to 0 -and (after setting any cipher parameters) it should be called again -with B set to NULL. - -=head1 SEE ALSO - -L, L, -L, -L - -=head1 HISTORY - -EVP_SealFinal() did not return a value before OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_SignInit.pod b/src/lib/libcrypto/doc/EVP_SignInit.pod deleted file mode 100644 index 6882211e02..0000000000 --- a/src/lib/libcrypto/doc/EVP_SignInit.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -EVP_SignInit, EVP_SignUpdate, EVP_SignFinal, EVP_PKEY_size -- EVP signing functions - -=head1 SYNOPSIS - - #include - - int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); - int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); - int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); - - void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); - - int EVP_PKEY_size(EVP_PKEY *pkey); - -=head1 DESCRIPTION - -The EVP signature routines are a high level interface to digital -signatures. - -EVP_SignInit_ex() sets up signing context B to use digest -B from ENGINE B. B must be initialized with -EVP_MD_CTX_init() before calling this function. - -EVP_SignUpdate() hashes B bytes of data at B into the -signature context B. This function can be called several times on the -same B to include additional data. - -EVP_SignFinal() signs the data in B using the private key B and -places the signature in B. B must be at least EVP_PKEY_size(pkey) -bytes in size. B is an OUT parameter, and not used as an IN parameter. -The number of bytes of data written (i.e. the length of the signature) -will be written to the integer at B, at most EVP_PKEY_size(pkey) bytes -will be written. - -EVP_SignInit() initializes a signing context B to use the default -implementation of digest B. - -EVP_PKEY_size() returns the maximum size of a signature in bytes. The actual -signature returned by EVP_SignFinal() may be smaller. - -=head1 RETURN VALUES - -EVP_SignInit_ex(), EVP_SignUpdate() and EVP_SignFinal() return 1 -for success and 0 for failure. - -EVP_PKEY_size() returns the maximum size of a signature in bytes. - -The error codes can be obtained by L. - -=head1 NOTES - -The B interface to digital signatures should almost always be used in -preference to the low level interfaces. This is because the code then becomes -transparent to the algorithm used and much more flexible. - -Due to the link between message digests and public key algorithms the correct -digest algorithm must be used with the correct public key type. A list of -algorithms and associated public key algorithms appears in -L. - -The call to EVP_SignFinal() internally finalizes a copy of the digest context. -This means that calls to EVP_SignUpdate() and EVP_SignFinal() can be called -later to digest and sign additional data. - -Since only a copy of the digest context is ever finalized the context must -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -=head1 BUGS - -Older versions of this documentation wrongly stated that calls to -EVP_SignUpdate() could not be made after calling EVP_SignFinal(). - -Since the private key is passed in the call to EVP_SignFinal() any error -relating to the private key (for example an unsuitable key and digest -combination) will not be indicated until after potentially large amounts of -data have been passed through EVP_SignUpdate(). - -It is not possible to change the signing parameters using these function. - -The previous two bugs are fixed in the newer EVP_SignDigest*() function. - -=head1 SEE ALSO - -L, -L, L, -L, L, L, -L, L, -L, L - -=head1 HISTORY - -EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_SignInit_ex() was added in OpenSSL 0.9.7. - -=cut diff --git a/src/lib/libcrypto/doc/EVP_VerifyInit.pod b/src/lib/libcrypto/doc/EVP_VerifyInit.pod deleted file mode 100644 index b0d3f8e4c9..0000000000 --- a/src/lib/libcrypto/doc/EVP_VerifyInit.pod +++ /dev/null @@ -1,96 +0,0 @@ -=pod - -=head1 NAME - -EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification -functions - -=head1 SYNOPSIS - - #include - - int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); - int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); - int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey); - - int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); - -=head1 DESCRIPTION - -The EVP signature verification routines are a high level interface to digital -signatures. - -EVP_VerifyInit_ex() sets up verification context B to use digest -B from ENGINE B. B must be initialized by calling -EVP_MD_CTX_init() before calling this function. - -EVP_VerifyUpdate() hashes B bytes of data at B into the -verification context B. This function can be called several times on the -same B to include additional data. - -EVP_VerifyFinal() verifies the data in B using the public key B -and against the B bytes at B. - -EVP_VerifyInit() initializes verification context B to use the default -implementation of digest B. - -=head1 RETURN VALUES - -EVP_VerifyInit_ex() and EVP_VerifyUpdate() return 1 for success and 0 for -failure. - -EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if -some other error occurred. - -The error codes can be obtained by L. - -=head1 NOTES - -The B interface to digital signatures should almost always be used in -preference to the low level interfaces. This is because the code then becomes -transparent to the algorithm used and much more flexible. - -Due to the link between message digests and public key algorithms the correct -digest algorithm must be used with the correct public key type. A list of -algorithms and associated public key algorithms appears in -L. - -The call to EVP_VerifyFinal() internally finalizes a copy of the digest context. -This means that calls to 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 -be cleaned up after use by calling EVP_MD_CTX_cleanup() or a memory leak -will occur. - -=head1 BUGS - -Older versions of this documentation wrongly stated that calls to -EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal(). - -Since the public key is passed in the call to EVP_SignFinal() any error -relating to the private key (for example an unsuitable key and digest -combination) will not be indicated until after potentially large amounts of -data have been passed through EVP_SignUpdate(). - -It is not possible to change the signing parameters using these function. - -The previous two bugs are fixed in the newer EVP_VerifyDigest*() function. - -=head1 SEE ALSO - -L, -L, -L, L, -L, L, L, -L, L, -L, L - -=head1 HISTORY - -EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are -available in all versions of SSLeay and OpenSSL. - -EVP_VerifyInit_ex() was added in OpenSSL 0.9.7 - -=cut diff --git a/src/lib/libcrypto/doc/evp.pod b/src/lib/libcrypto/doc/evp.pod deleted file mode 100644 index dfd96d3b98..0000000000 --- a/src/lib/libcrypto/doc/evp.pod +++ /dev/null @@ -1,107 +0,0 @@ -=pod - -=head1 NAME - -evp - high-level cryptographic functions - -=head1 SYNOPSIS - - #include - -=head1 DESCRIPTION - -The EVP library provides a high-level interface to cryptographic -functions. - -LI<...>|EVP_SealInit(3)> and LI<...>|EVP_OpenInit(3)> -provide public key encryption and decryption to implement digital "envelopes". - -The LI<...>|EVP_DigestSignInit(3)> and -LI<...>|EVP_DigestVerifyInit(3)> functions implement -digital signatures and Message Authentication Codes (MACs). Also see the older -LI<...>|EVP_SignInit(3)> and LI<...>|EVP_VerifyInit(3)> -functions. - -Symmetric encryption is available with the LI<...>|EVP_EncryptInit(3)> -functions. The LI<...>|EVP_DigestInit(3)> functions provide message digests. - -Authenticated encryption with additional data (AEAD) is available with -the LI<...>|EVP_AEAD_CTX_init(3)> functions. - -The BI<...> functions provide a high level interface to -asymmetric algorithms. To create a new EVP_PKEY see -L. EVP_PKEYs can be associated -with a private key of a particular algorithm by using the functions -described on the L page, or -new keys can be generated using L. -EVP_PKEYs can be compared using L, or printed using -L. - -The EVP_PKEY functions support the full range of asymmetric algorithm operations: - -=over - -=item For key agreement see L - -=item For signing and verifying see L, -L and L. -However, note that -these functions do not perform a digest of the data to be signed. Therefore -normally you would use the LI<...>|EVP_DigestSignInit(3)> -functions for this purpose. - -=item For encryption and decryption see L -and L respectively. However, note that -these functions perform encryption and decryption only. As public key -encryption is an expensive operation, normally you would wrap -an encrypted message in a "digital envelope" using the LI<...>|EVP_SealInit(3)> and -LI<...>|EVP_OpenInit(3)> functions. - -=back - -The L function provides some limited support for password -based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible -implementation. However, new applications should not typically use this (preferring, for example, -PBKDF2 from PCKS#5). - -Algorithms are loaded with L. - -All the symmetric algorithms (ciphers), digests and asymmetric algorithms -(public key algorithms) can be replaced by L modules providing alternative -implementations. If ENGINE implementations of ciphers or digests are registered -as defaults, then the various EVP functions will automatically use those -implementations automatically in preference to built in software -implementations. For more information, consult the engine(3) man page. - -Although low level algorithm specific functions exist for many algorithms -their use is discouraged. They cannot be used with an ENGINE and ENGINE -versions of new algorithms cannot be accessed using the low level functions. -Also makes code harder to adapt to new algorithms and some options are not -cleanly supported at the low level and some operations are more efficient -using the high level interface. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut -- cgit v1.2.3-55-g6feb