From 4d607f17ea3eb38ed9f7703afd423f6055c686d4 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 --- src/lib/libcrypto/man/EVP_BytesToKey.3 | 82 ++ src/lib/libcrypto/man/EVP_DigestInit.3 | 520 ++++++++++++ src/lib/libcrypto/man/EVP_DigestSignInit.3 | 152 ++++ src/lib/libcrypto/man/EVP_DigestVerifyInit.3 | 132 +++ src/lib/libcrypto/man/EVP_EncryptInit.3 | 939 +++++++++++++++++++++ src/lib/libcrypto/man/EVP_OpenInit.3 | 98 +++ src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 | 245 ++++++ src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 | 85 ++ src/lib/libcrypto/man/EVP_PKEY_cmp.3 | 92 ++ src/lib/libcrypto/man/EVP_PKEY_decrypt.3 | 117 +++ src/lib/libcrypto/man/EVP_PKEY_derive.3 | 120 +++ src/lib/libcrypto/man/EVP_PKEY_encrypt.3 | 117 +++ .../libcrypto/man/EVP_PKEY_get_default_digest.3 | 39 + src/lib/libcrypto/man/EVP_PKEY_keygen.3 | 235 ++++++ src/lib/libcrypto/man/EVP_PKEY_new.3 | 44 + src/lib/libcrypto/man/EVP_PKEY_print_private.3 | 76 ++ src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 | 171 ++++ src/lib/libcrypto/man/EVP_PKEY_sign.3 | 120 +++ src/lib/libcrypto/man/EVP_PKEY_verify.3 | 109 +++ src/lib/libcrypto/man/EVP_PKEY_verify_recover.3 | 131 +++ src/lib/libcrypto/man/EVP_SealInit.3 | 131 +++ src/lib/libcrypto/man/EVP_SignInit.3 | 167 ++++ src/lib/libcrypto/man/EVP_VerifyInit.3 | 146 ++++ src/lib/libcrypto/man/Makefile | 20 +- src/lib/libcrypto/man/evp.3 | 151 ++++ 49 files changed, 4229 insertions(+), 2724 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 create mode 100644 src/lib/libcrypto/man/EVP_BytesToKey.3 create mode 100644 src/lib/libcrypto/man/EVP_DigestInit.3 create mode 100644 src/lib/libcrypto/man/EVP_DigestSignInit.3 create mode 100644 src/lib/libcrypto/man/EVP_DigestVerifyInit.3 create mode 100644 src/lib/libcrypto/man/EVP_EncryptInit.3 create mode 100644 src/lib/libcrypto/man/EVP_OpenInit.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_cmp.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_decrypt.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_derive.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_encrypt.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_get_default_digest.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_keygen.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_new.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_print_private.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_sign.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_verify.3 create mode 100644 src/lib/libcrypto/man/EVP_PKEY_verify_recover.3 create mode 100644 src/lib/libcrypto/man/EVP_SealInit.3 create mode 100644 src/lib/libcrypto/man/EVP_SignInit.3 create mode 100644 src/lib/libcrypto/man/EVP_VerifyInit.3 create mode 100644 src/lib/libcrypto/man/evp.3 (limited to 'src') 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 diff --git a/src/lib/libcrypto/man/EVP_BytesToKey.3 b/src/lib/libcrypto/man/EVP_BytesToKey.3 new file mode 100644 index 0000000000..45a3d9bf33 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_BytesToKey.3 @@ -0,0 +1,82 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_BYTESTOKEY 3 +.Os +.Sh NAME +.Nm EVP_BytesToKey +.Nd password based encryption routine +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_BytesToKey +.Fa "const EVP_CIPHER *type" +.Fa "const EVP_MD *md" +.Fa "const unsigned char *salt" +.Fa "const unsigned char *data" +.Fa "int datal" +.Fa "int count" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fc +.Sh DESCRIPTION +.Fn EVP_BytesToKey +derives a key and IV from various parameters. +.Fa type +is the cipher to derive the key and IV for. +.Fa md +is the message digest to use. +The +.Fa salt +parameter is used as a salt in the derivation: it should point to an 8 +byte buffer or +.Dv NULL +if no salt is used. +.Fa data +is a buffer containing +.Fa datal +bytes which is used to derive the keying data. +.Fa count +is the iteration count to use. +The derived key and IV will be written to +.Fa key +and +.Fa iv , +respectively. +.Pp +A typical application of this function is to derive keying material for +an encryption algorithm from a password in the +.Fa data +parameter. +.Pp +Increasing the +.Fa count +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. +.Pp +If the total key and IV length is less than the digest length and MD5 +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. +.Pp +Newer applications should use more standard algorithms such as PBKDF2 as +defined in PKCS#5v2.1 for key derivation. +.Sh 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 recursively as: +.Pp +.Dl D_i = HASH^count(D_(i-1) || data || salt) +.Pp +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. +.Pp +The initial bytes are used for the key and the subsequent bytes for the +IV. +.Sh RETURN VALUES +.Fn EVP_BytesToKey +returns the size of the derived key in bytes. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 , +.Xr PKCS5_PBKDF2_HMAC 3 , +.Xr rand 3 diff --git a/src/lib/libcrypto/man/EVP_DigestInit.3 b/src/lib/libcrypto/man/EVP_DigestInit.3 new file mode 100644 index 0000000000..9bcf79241c --- /dev/null +++ b/src/lib/libcrypto/man/EVP_DigestInit.3 @@ -0,0 +1,520 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_DIGESTINIT 3 +.Os +.Sh NAME +.Nm EVP_MD_CTX_init , +.Nm EVP_MD_CTX_create , +.Nm EVP_DigestInit_ex , +.Nm EVP_DigestUpdate , +.Nm EVP_DigestFinal_ex , +.Nm EVP_MD_CTX_cleanup , +.Nm EVP_MD_CTX_destroy , +.Nm EVP_MAX_MD_SIZE , +.Nm EVP_MD_CTX_copy_ex , +.Nm EVP_MD_CTX_copy , +.Nm EVP_MD_type , +.Nm EVP_MD_pkey_type , +.Nm EVP_MD_size , +.Nm EVP_MD_block_size , +.Nm EVP_MD_CTX_md , +.Nm EVP_MD_CTX_size , +.Nm EVP_MD_CTX_block_size , +.Nm EVP_MD_CTX_type , +.Nm EVP_md_null , +.Nm EVP_md2 , +.Nm EVP_md5 , +.Nm EVP_sha1 , +.Nm EVP_sha224 , +.Nm EVP_sha256 , +.Nm EVP_sha384 , +.Nm EVP_sha512 , +.Nm EVP_dss , +.Nm EVP_dss1 , +.Nm EVP_ripemd160 , +.Nm EVP_get_digestbyname , +.Nm EVP_get_digestbynid , +.Nm EVP_get_digestbyobj , +.Nm EVP_DigestInit , +.Nm EVP_DigestFinal +.Nd EVP digest routines +.Sh SYNOPSIS +.In openssl/evp.h +.Ft void +.Fo EVP_MD_CTX_init +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft EVP_MD_CTX * +.Fn EVP_MD_CTX_create void +.Ft int +.Fo EVP_DigestInit_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *impl" +.Fc +.Ft int +.Fo EVP_DigestUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "size_t cnt" +.Fc +.Ft int +.Fo EVP_DigestFinal_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *md" +.Fa "unsigned int *s" +.Fc +.Ft int +.Fo EVP_MD_CTX_cleanup +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft void +.Fo EVP_MD_CTX_destroy +.Fa "EVP_MD_CTX *ctx" +.Fc +.Ft int +.Fo EVP_MD_CTX_copy_ex +.Fa "EVP_MD_CTX *out" +.Fa "const EVP_MD_CTX *in" +.Fc +.Ft int +.Fo EVP_DigestInit +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fc +.Ft int +.Fo EVP_DigestFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *md" +.Fa "unsigned int *s" +.Fc +.Ft int +.Fo EVP_MD_CTX_copy +.Fa "EVP_MD_CTX *out" +.Fa "EVP_MD_CTX *in" +.Fc +.Fd #define EVP_MAX_MD_SIZE 64 /* SHA512 */ +.Ft int +.Fo EVP_MD_type +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_pkey_type +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_size +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_MD_block_size +.Fa "const EVP_MD *md" +.Fc +.Ft const EVP_MD * +.Fo EVP_MD_CTX_md +.Fa "const EVP_MD_CTX *ctx" +.Fc +.Fd #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) +.Fd #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) +.Fd #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) +.Ft const EVP_MD * +.Fn EVP_md_null void +.Ft const EVP_MD * +.Fn EVP_md2 void +.Ft const EVP_MD * +.Fn EVP_md5 void +.Ft const EVP_MD * +.Fn EVP_sha1 void +.Ft const EVP_MD * +.Fn EVP_dss void +.Ft const EVP_MD * +.Fn EVP_dss1 void +.Ft const EVP_MD * +.Fn EVP_ripemd160 void +.Ft const EVP_MD * +.Fn EVP_sha224 void +.Ft const EVP_MD * +.Fn EVP_sha256 void +.Ft const EVP_MD * +.Fn EVP_sha384 void +.Ft const EVP_MD * +.Fn EVP_sha512 void +.Ft const EVP_MD * +.Fo EVP_get_digestbyname +.Fa "const char *name" +.Fc +.Fd #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) +.Fd #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) +.Sh DESCRIPTION +The EVP digest routines are a high level interface to message digests. +.Pp +.Fn EVP_MD_CTX_init +initializes the digest context +.Fa ctx . +.Pp +.Fn EVP_MD_CTX_create +allocates, initializes, and returns a digest context. +.Pp +.Fn EVP_DigestInit_ex +sets up digest context +.Fa ctx +to use a digest +.Fa type +from +.Vt ENGINE +.Fa impl . +.Fa ctx +must be initialized before calling this function. +.Fa type +will typically be supplied by a function such as +.Fn EVP_sha1 . +If +.Fa impl +is +.Dv NULL , +then the default implementation of digest +.Fa type +is used. +.Pp +.Fn EVP_DigestUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the digest context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to hash additional data. +.Pp +.Fn EVP_DigestFinal_ex +retrieves the digest value from +.Fa ctx +and places it in +.Fa md . +If the +.Fa s +parameter is not +.Dv NULL , +then the number of bytes of data written (i.e. the length of the +digest) will be written to the integer at +.Fa s , +at most +.Dv EVP_MAX_MD_SIZE +bytes will be written. +After calling +.Fn EVP_DigestFinal_ex , +no additional calls to +.Fn EVP_DigestUpdate +can be made, but +.Fn EVP_DigestInit_ex +can be called to initialize a new digest operation. +.Pp +.Fn EVP_MD_CTX_cleanup +cleans up the digest context +.Fa ctx . +It should be called after a digest context is no longer needed. +.Pp +.Fn EVP_MD_CTX_destroy +cleans up the digest context +.Fa ctx +and frees up the space allocated to it. +It should be called only on a context created using +.Fn EVP_MD_CTX_create . +.Pp +.Fn EVP_MD_CTX_copy_ex +can be used to copy the message digest state from +.Fa in +to +.Fa out . +This is useful if large amounts of data are to be hashed which only +differ in the last few bytes. +.Fa out +must be initialized before calling this function. +.Pp +.Fn EVP_DigestInit +behaves in the same way as +.Fn EVP_DigestInit_ex +except the passed context +.Fa ctx +does not have to be initialized, and it always uses the default digest +implementation. +.Pp +.Fn EVP_DigestFinal +is similar to +.Fn EVP_DigestFinal_ex +except the digest context +.Fa ctx +is automatically cleaned up. +.Pp +.Fn EVP_MD_CTX_copy +is similar to +.Fn EVP_MD_CTX_copy_ex +except the destination +.Fa out +does not have to be initialized. +.Pp +.Fn EVP_MD_size +and +.Fn EVP_MD_CTX_size +return the size of the message digest when passed an +.Vt EVP_MD +or an +.Vt EVP_MD_CTX +structure, i.e. the size of the hash. +.Pp +.Fn EVP_MD_block_size +and +.Fn EVP_MD_CTX_block_size +return the block size of the message digest when passed an +.Vt EVP_MD +or an +.Vt EVP_MD_CTX +structure. +.Pp +.Fn EVP_MD_type +and +.Fn EVP_MD_CTX_type +return the NID of the OBJECT IDENTIFIER representing the given message +digest when passed an +.Vt EVP_MD +structure. +For example +.Fn EVP_MD_type EVP_sha1() +returns +.Dv NID_sha1 . +This function is normally used when setting ASN1 OIDs. +.Pp +.Fn EVP_MD_CTX_md +returns the +.Vt EVP_MD +structure corresponding to the passed +.Vt EVP_MD_CTX . +.Pp +.Fn EVP_MD_pkey_type +returns the NID of the public key signing algorithm associated with this +digest. +For example +.Fn EVP_sha1 +is associated with RSA so this will return +.Dv NID_sha1WithRSAEncryption . +Since digests and signature algorithms are no longer linked this +function is only retained for compatibility reasons. +.Pp +.Fn EVP_md2 , +.Fn EVP_md5 , +.Fn EVP_sha1 , +.Fn EVP_sha224 , +.Fn EVP_sha256 , +.Fn EVP_sha384 , +.Fn EVP_sha512 , +and +.Fn EVP_ripemd160 +return +.Vt EVP_MD +structures for the MD2, MD5, SHA1, SHA224, SHA256, SHA384, SHA512 and +RIPEMD160 digest algorithms respectively. +.Pp +.Fn EVP_dss +and +.Fn EVP_dss1 +return +.Vt EVP_MD +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. +.Pp +.Fn EVP_md_null +is a "null" message digest that does nothing: +i.e. the hash it returns is of zero length. +.Pp +.Fn EVP_get_digestbyname , +.Fn EVP_get_digestbynid , +and +.Fn EVP_get_digestbyobj +return an +.Vt EVP_MD +structure when passed a digest name, a digest NID, or an ASN1_OBJECT +structure respectively. +The digest table must be initialized using, for example, +.Xr OpenSSL_add_all_digests 3 +for these functions to work. +.Pp +The EVP interface to message digests should almost always be used +in preference to the low level interfaces. +This is because the code then becomes transparent to the digest used and +much more flexible. +.Pp +New applications should use the SHA2 digest algorithms such as SHA256. +The other digest algorithms are still in common use. +.Pp +For most applications the +.Fa impl +parameter to +.Fn EVP_DigestInit_ex +will be set to NULL to use the default digest implementation. +.Pp +The functions +.Fn EVP_DigestInit , +.Fn EVP_DigestFinal , +and +.Fn EVP_MD_CTX_copy +are obsolete but are retained to maintain compatibility with existing +code. +New applications should use +.Fn EVP_DigestInit_ex , +.Fn EVP_DigestFinal_ex , +and +.Fn 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. +.Pp +In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after +use memory leaks will occur. +.Pp +Stack allocation of +.Vt EVP_MD_CTX +structures is common, for example: +.Bd -literal -offset indent +EVP_MD_CTX mctx; +EVP_MD_CTX_init(&mctx); +.Ed +.Pp +This will cause binary compatibility issues if the size of +.Vt EVP_MD_CTX +structure changes (this will only happen with a major release of OpenSSL). +Applications wishing to avoid this should use +.Fn EVP_MD_CTX_create +instead: +.Bd -literal -offset indent +EVP_MD_CTX *mctx; +mctx = EVP_MD_CTX_create(); +.Ed +.Sh RETURN VALUES +.Fn EVP_DigestInit_ex , +.Fn EVP_DigestUpdate , +.Fn EVP_DigestFinal_ex , +and +.Fn EVP_MD_CTX_copy_ex +return 1 for success or 0 for failure. +.Pp +.Fn EVP_MD_type , +.Fn EVP_MD_pkey_type , +and +.Fn EVP_MD_type +return the NID of the corresponding OBJECT IDENTIFIER or +.Dv NID_undef +if none exists. +.Pp +.Fn EVP_MD_size , +.Fn EVP_MD_block_size , +.Fn EVP_MD_CTX_size , +and +.Fn EVP_MD_CTX_block_size +return the digest or block size in bytes. +.Pp +.Fn EVP_md_null , +.Fn EVP_md2 , +.Fn EVP_md5 , +.Fn EVP_sha1 , +.Fn EVP_dss , +.Fn EVP_dss1 , +and +.Fn EVP_ripemd160 +return pointers to the corresponding +.Vt EVP_MD +structures. +.Pp +.Fn EVP_get_digestbyname , +.Fn EVP_get_digestbynid , +and +.Fn EVP_get_digestbyobj +return either an +.Vt EVP_MD +structure or +.Dv NULL +if an error occurs. +.Sh EXAMPLES +This example digests the data "Test Message\en" and "Hello World\en", +using the digest name passed on the command line. +.Bd -literal +#include +#include + +int +main(int argc, char *argv[]) +{ + EVP_MD_CTX *mdctx; + const EVP_MD *md; + const char mess1[] = "Test Message\en"; + const char mess2[] = "Hello World\en"; + unsigned char md_value[EVP_MAX_MD_SIZE]; + int md_len, i; + + OpenSSL_add_all_digests(); + + if (argc <= 1) { + printf("Usage: mdtest digestname\en"); + exit(1); + } + + md = EVP_get_digestbyname(argv[1]); + if (md == NULL) { + printf("Unknown message digest %s\en", 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("\en"); +} +.Ed +.Sh SEE ALSO +.Xr evp 3 +.Sh HISTORY +.Fn EVP_DigestInit , +.Fn EVP_DigestUpdate , +and +.Fn EVP_DigestFinal +are available in all versions of SSLeay and OpenSSL. +.Pp +.Fn EVP_MD_CTX_init , +.Fn EVP_MD_CTX_create , +.Fn EVP_MD_CTX_copy_ex , +.Fn EVP_MD_CTX_cleanup , +.Fn EVP_MD_CTX_destroy , +.Fn EVP_DigestInit_ex , +and +.Fn EVP_DigestFinal_ex +were added in OpenSSL 0.9.7. +.Pp +.Fn EVP_md_null , +.Fn EVP_md2 , +.Fn EVP_md5 , +.Fn EVP_sha1 , +.Fn EVP_dss , +.Fn EVP_dss1 , +and +.Fn EVP_ripemd160 +were changed to return truely const +.Vt EVP_MD +pointers in OpenSSL 0.9.7. +.Pp +The link between digests and signing algorithms was fixed in OpenSSL 1.0 +and later, so now +.Fn EVP_sha1 +can be used with RSA and DSA, there is no need to use +.Fn EVP_dss1 +any more. +.Pp +OpenSSL 1.0 and later does not include the MD2 digest algorithm in the +default configuration due to its security weaknesses. diff --git a/src/lib/libcrypto/man/EVP_DigestSignInit.3 b/src/lib/libcrypto/man/EVP_DigestSignInit.3 new file mode 100644 index 0000000000..89a2d7afbd --- /dev/null +++ b/src/lib/libcrypto/man/EVP_DigestSignInit.3 @@ -0,0 +1,152 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_DIGESTSIGNINIT 3 +.Os +.Sh NAME +.Nm EVP_DigestSignInit , +.Nm EVP_DigestSignUpdate , +.Nm EVP_DigestSignFinal +.Nd EVP signing functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_DigestSignInit +.Fa "EVP_MD_CTX *ctx" +.Fa "EVP_PKEY_CTX **pctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *e" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_DigestSignUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "unsigned int cnt" +.Fc +.Ft int +.Fo EVP_DigestSignFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sig" +.Fa "size_t *siglen" +.Fc +.Sh DESCRIPTION +The EVP signature routines are a high level interface to digital +signatures. +.Pp +.Fn EVP_DigestSignInit +sets up the signing context +.Fa ctx +to use the digest +.Fa type +from +.Vt ENGINE +.Fa e +and private key +.Fa pkey . +.Fa ctx +must be initialized with +.Xr EVP_MD_CTX_init 3 +before calling this function. +If +.Fa pctx +is not +.Dv NULL , +the +.Vt EVP_PKEY_CTX +of the signing operation will be written to +.Pf * Fa pctx : +this can be used to set alternative signing options. +.Pp +.Fn EVP_DigestSignUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the signature context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +This function is currently implemented using a macro. +.Pp +.Fn EVP_DigestSignFinal +signs the data in +.Fa ctx +and places the signature in +.Fa sig . +If +.Fa sig +is +.Dv NULL , +then the maximum size of the output buffer is written to +.Pf * Fa siglen . +If +.Fa sig +is not +.Dv NULL , +then before the call +.Fa siglen +should contain the length of the +.Fa sig +buffer. +If the call is successful, the signature is written to +.Fa sig +and the amount of data written to +.Fa siglen . +.Pp +The EVP 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. +.Pp +In previous versions of OpenSSL, there was a link between message digest +types and public key algorithms. +This meant that "clone" digests such as +.Xr EVP_dss1 3 +needed to be used to sign using SHA1 and DSA. +This is no longer necessary and the use of clone digest is now +discouraged. +.Pp +The call to +.Fn EVP_DigestSignFinal +internally finalizes a copy of the digest context. +This means that +.Fn EVP_DigestSignUpdate +and +.Fn EVP_DigestSignFinal +can be called later to digest and sign additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_cleanup 3 , +or a memory leak will occur. +.Pp +The use of +.Xr EVP_PKEY_size 3 +with these functions is discouraged because some signature operations +may have a signature length which depends on the parameters set. +As a result, +.Xr EVP_PKEY_size 3 +would have to return a value which indicates the maximum possible +signature for any set of parameters. +.Sh RETURN VALUES +.Fn EVP_DigestSignInit , +.Fn EVP_DigestSignUpdate , +and +.Fn EVP_DigestSignFinal +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. +.Pp +The error codes can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR 3 , +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_DigestVerifyInit 3 +.Sh HISTORY +.Fn EVP_DigestSignInit , +.Fn EVP_DigestSignUpdate , +and +.Fn EVP_DigestSignFinal +were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_DigestVerifyInit.3 b/src/lib/libcrypto/man/EVP_DigestVerifyInit.3 new file mode 100644 index 0000000000..0b26eb617e --- /dev/null +++ b/src/lib/libcrypto/man/EVP_DigestVerifyInit.3 @@ -0,0 +1,132 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_DIGESTVERIFYINIT 3 +.Os +.Sh NAME +.Nm EVP_DigestVerifyInit , +.Nm EVP_DigestVerifyUpdate , +.Nm EVP_DigestVerifyFinal +.Nd EVP signature verification functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_DigestVerifyInit +.Fa "EVP_MD_CTX *ctx" +.Fa "EVP_PKEY_CTX **pctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *e" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_DigestVerifyUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "unsigned int cnt" +.Fc +.Ft int +.Fo EVP_DigestVerifyFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sig" +.Fa "size_t siglen" +.Fc +.Sh DESCRIPTION +The EVP signature routines are a high level interface to digital +signatures. +.Pp +.Fn EVP_DigestVerifyInit +sets up verification context +.Fa ctx +to use digest +.Fa type +from +.Vt ENGINE +.Fa e +and public key +.Fa pkey . +.Fa ctx +must be initialized with +.Xr EVP_MD_CTX_init 3 +before calling this function. +If +.Fa pctx +is not +.Dv NULL , +the +.Vt EVP_PKEY_CTX +of the verification operation will be written to +.Pf * Fa pctx : +this can be used to set alternative verification options. +.Pp +.Fn EVP_DigestVerifyUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the verification context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +This function is currently implemented using a macro. +.Pp +.Fn EVP_DigestVerifyFinal +verifies the data in +.Fa ctx +against the signature in +.Fa sig +of length +.Fa siglen . +.Pp +The EVP 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. +.Pp +In previous versions of OpenSSL, there was a link between message digest +types and public key algorithms. +This meant that "clone" digests such as +.Xr EVP_dss1 3 +needed to be used to sign using SHA1 and DSA. +This is no longer necessary and the use of clone digest is now +discouraged. +.Pp +The call to +.Fn EVP_DigestVerifyFinal +internally finalizes a copy of the digest context. +This means that calls to +.Xr EVP_VerifyUpdate 3 +and +.Xr EVP_VerifyFinal 3 +can be called later to digest and verify additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_cleanup 3 +or a memory leak will occur. +.Sh RETURN VALUES +.Fn EVP_DigestVerifyInit +and +.Fn 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. +.Pp +Unlike other functions, the return value 0 from +.Fn EVP_DigestVerifyFinal +only indicates that the signature did not verify successfully. +That is it did not match the original data or the signature was of +invalid form. +It is not an indication of a more serious error. +.Pp +The error codes can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR 3 , +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_DigestSignInit 3 +.Sh HISTORY +.Fn EVP_DigestVerifyInit , +.Fn EVP_DigestVerifyUpdate , +and +.Fn EVP_DigestVerifyFinal +were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_EncryptInit.3 b/src/lib/libcrypto/man/EVP_EncryptInit.3 new file mode 100644 index 0000000000..44967f863f --- /dev/null +++ b/src/lib/libcrypto/man/EVP_EncryptInit.3 @@ -0,0 +1,939 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_ENCRYPTINIT 3 +.Os +.Sh NAME +.Nm EVP_CIPHER_CTX_init , +.Nm EVP_EncryptInit_ex , +.Nm EVP_EncryptUpdate , +.Nm EVP_EncryptFinal_ex , +.Nm EVP_DecryptInit_ex , +.Nm EVP_DecryptUpdate , +.Nm EVP_DecryptFinal_ex , +.Nm EVP_CipherInit_ex , +.Nm EVP_CipherUpdate , +.Nm EVP_CipherFinal_ex , +.Nm EVP_CIPHER_CTX_set_key_length , +.Nm EVP_CIPHER_CTX_ctrl , +.Nm EVP_CIPHER_CTX_cleanup , +.Nm EVP_EncryptInit , +.Nm EVP_EncryptFinal , +.Nm EVP_DecryptInit , +.Nm EVP_DecryptFinal , +.Nm EVP_CipherInit , +.Nm EVP_CipherFinal , +.Nm EVP_get_cipherbyname , +.Nm EVP_get_cipherbynid , +.Nm EVP_get_cipherbyobj , +.Nm EVP_CIPHER_nid , +.Nm EVP_CIPHER_block_size , +.Nm EVP_CIPHER_key_length , +.Nm EVP_CIPHER_iv_length , +.Nm EVP_CIPHER_flags , +.Nm EVP_CIPHER_mode , +.Nm EVP_CIPHER_type , +.Nm EVP_CIPHER_CTX_cipher , +.Nm EVP_CIPHER_CTX_nid , +.Nm EVP_CIPHER_CTX_block_size , +.Nm EVP_CIPHER_CTX_key_length , +.Nm EVP_CIPHER_CTX_iv_length , +.Nm EVP_CIPHER_CTX_get_app_data , +.Nm EVP_CIPHER_CTX_set_app_data , +.Nm EVP_CIPHER_CTX_type , +.Nm EVP_CIPHER_CTX_flags , +.Nm EVP_CIPHER_CTX_mode , +.Nm EVP_CIPHER_param_to_asn1 , +.Nm EVP_CIPHER_asn1_to_param , +.Nm EVP_CIPHER_CTX_set_padding , +.Nm EVP_enc_null , +.Nm EVP_des_cbc , +.Nm EVP_des_ecb , +.Nm EVP_des_cfb , +.Nm EVP_des_ofb , +.Nm EVP_des_ede_cbc , +.Nm EVP_des_ede , +.Nm EVP_des_ede_ofb , +.Nm EVP_des_ede_cfb , +.Nm EVP_des_ede3_cbc , +.Nm EVP_des_ede3 , +.Nm EVP_des_ede3_ofb , +.Nm EVP_des_ede3_cfb , +.Nm EVP_desx_cbc , +.Nm EVP_rc4 , +.Nm EVP_rc4_40 , +.Nm EVP_idea_cbc , +.Nm EVP_idea_ecb , +.Nm EVP_idea_cfb , +.Nm EVP_idea_ofb , +.Nm EVP_idea_cbc , +.Nm EVP_rc2_cbc , +.Nm EVP_rc2_ecb , +.Nm EVP_rc2_cfb , +.Nm EVP_rc2_ofb , +.Nm EVP_rc2_40_cbc , +.Nm EVP_rc2_64_cbc , +.Nm EVP_bf_cbc , +.Nm EVP_bf_ecb , +.Nm EVP_bf_cfb , +.Nm EVP_bf_ofb , +.Nm EVP_cast5_cbc , +.Nm EVP_cast5_ecb , +.Nm EVP_cast5_cfb , +.Nm EVP_cast5_ofb , +.Nm EVP_aes_128_gcm , +.Nm EVP_aes_192_gcm , +.Nm EVP_aes_256_gcm , +.Nm EVP_aes_128_ccm , +.Nm EVP_aes_192_ccm , +.Nm EVP_aes_256_ccm , +.Nm EVP_rc5_32_12_16_cbc , +.Nm EVP_rc5_32_12_16_cfb , +.Nm EVP_rc5_32_12_16_ecb , +.Nm EVP_rc5_32_12_16_ofb +.Nd EVP cipher routines +.Sh SYNOPSIS +.In openssl/evp.h +.Ft void +.Fo EVP_CIPHER_CTX_init +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft int +.Fo EVP_EncryptInit_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "ENGINE *impl" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fc +.Ft int +.Fo EVP_EncryptUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_EncryptFinal_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_DecryptInit_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "ENGINE *impl" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fc +.Ft int +.Fo EVP_DecryptUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_DecryptFinal_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *outm" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_CipherInit_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "ENGINE *impl" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fa "int enc" +.Fc +.Ft int +.Fo EVP_CipherUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_CipherFinal_ex +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *outm" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_EncryptInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fc +.Ft int +.Fo EVP_EncryptFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_DecryptInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fc +.Ft int +.Fo EVP_DecryptFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *outm" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_CipherInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "unsigned char *key" +.Fa "unsigned char *iv" +.Fa "int enc" +.Fc +.Ft int +.Fo EVP_CipherFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *outm" +.Fa "int *outl" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_set_padding +.Fa "EVP_CIPHER_CTX *x" +.Fa "int padding" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_set_key_length +.Fa "EVP_CIPHER_CTX *x" +.Fa "int keylen" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_ctrl +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "int type" +.Fa "int arg" +.Fa "void *ptr" +.Fc +.Ft int +.Fo EVP_CIPHER_CTX_cleanup +.Fa "EVP_CIPHER_CTX *ctx" +.Fc +.Ft const EVP_CIPHER * +.Fo EVP_get_cipherbyname +.Fa "const char *name" +.Fc +.Fd #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) +.Fd #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) +.Fd #define EVP_CIPHER_nid(e) ((e)->nid) +.Fd #define EVP_CIPHER_block_size(e) ((e)->block_size) +.Fd #define EVP_CIPHER_key_length(e) ((e)->key_len) +.Fd #define EVP_CIPHER_iv_length(e) ((e)->iv_len) +.Fd #define EVP_CIPHER_flags(e) ((e)->flags) +.Fd #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE) +.Ft int +.Fo EVP_CIPHER_type +.Fa "const EVP_CIPHER *ctx" +.Fc +.Fd #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) +.Fd #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) +.Fd #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) +.Fd #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len) +.Fd #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) +.Fd #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data) +.Fd #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d)) +.Fd #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) +.Fd #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags) +.Fd #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE) +.Ft int +.Fo EVP_CIPHER_param_to_asn1 +.Fa "EVP_CIPHER_CTX *c" +.Fa "ASN1_TYPE *type" +.Fc +.Ft int +.Fo EVP_CIPHER_asn1_to_param +.Fa "EVP_CIPHER_CTX *c" +.Fa "ASN1_TYPE *type" +.Fc +.Sh DESCRIPTION +The EVP cipher routines are a high level interface to certain symmetric +ciphers. +.Pp +.Fn EVP_CIPHER_CTX_init +initializes the cipher context +.Fa ctx . +.Pp +.Fn EVP_EncryptInit_ex +sets up the cipher context +.Fa ctx +for encryption with cipher +.Fa type +from +.Vt ENGINE +.Fa impl . +.Fa ctx +must be initialized before calling this function. +.Fa type +is normally supplied by a function such as +.Fn EVP_aes_256_cbc . +If +.Fa impl +is +.Dv NULL , +then the default implementation is used. +.Fa key +is the symmetric key to use and +.Fa iv +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 +.Dv NULL +except +.Fa type +in an initial call and supply the remaining parameters in subsequent +calls, all of which have +.Fa type +set to +.Dv NULL . +This is done when the default cipher parameters are not appropriate. +.Pp +.Fn EVP_EncryptUpdate +encrypts +.Fa inl +bytes from the buffer +.Fa in +and writes the encrypted version to +.Fa out . +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 +.Fa outl +should contain sufficient room. +The actual number of bytes written is placed in +.Fa outl . +.Pp +If padding is enabled (the default) then +.Fn EVP_EncryptFinal_ex +encrypts the "final" data, that is any data that remains in a partial +block. +It uses NOTES (aka PKCS padding). +The encrypted final data is written to +.Fa out +which should have sufficient space for one cipher block. +The number of bytes written is placed in +.Fa outl . +After this function is called the encryption operation is finished and +no further calls to +.Fn EVP_EncryptUpdate +should be made. +.Pp +If padding is disabled then +.Fn 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. +.Pp +.Fn EVP_DecryptInit_ex , +.Fn EVP_DecryptUpdate , +and +.Fn EVP_DecryptFinal_ex +are the corresponding decryption operations. +.Fn 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 +.Fa out +passed to +.Fn EVP_DecryptUpdate +should have sufficient room for (inl + cipher_block_size) bytes +unless the cipher block size is 1 in which case +.Fa inl +bytes is sufficient. +.Pp +.Fn EVP_CipherInit_ex , +.Fn EVP_CipherUpdate , +and +.Fn EVP_CipherFinal_ex +are functions that can be used for decryption or encryption. +The operation performed depends on the value of the +.Fa enc +parameter. +It should be set to 1 for encryption, 0 for decryption and -1 to leave +the value unchanged (the actual value of +.Fa enc +being supplied in a previous call). +.Pp +.Fn 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. +.Pp +.Fn EVP_EncryptInit , +.Fn EVP_DecryptInit , +and +.Fn EVP_CipherInit +behave in a similar way to +.Fn EVP_EncryptInit_ex , +.Fn EVP_DecryptInit_ex , +and +.Fn EVP_CipherInit_ex +except the +.Fa ctx +parameter does not need to be initialized and they always use the +default cipher implementation. +.Pp +.Fn EVP_EncryptFinal , +.Fn EVP_DecryptFinal , +and +.Fn EVP_CipherFinal +are identical to +.Fn EVP_EncryptFinal_ex , +.Fn EVP_DecryptFinal_ex , +and +.Fn EVP_CipherFinal_ex . +In previous releases of OpenSSL, they also used to clean up the +.Fa ctx , +but this is no longer done and +.Fn EVP_CIPHER_CTX_cleanup +must be called to free any context resources. +.Pp +.Fn EVP_get_cipherbyname , +.Fn EVP_get_cipherbynid , +and +.Fn EVP_get_cipherbyobj +return an +.Vt EVP_CIPHER +structure when passed a cipher name, a NID or an +.Vt ASN1_OBJECT +structure. +.Pp +.Fn EVP_CIPHER_nid +and +.Fn EVP_CIPHER_CTX_nid +return the NID of a cipher when passed an +.Vt EVP_CIPHER +or +.Vt EVP_CIPHER_CTX +structure. +The actual NID value is an internal value which may not have a +corresponding OBJECT IDENTIFIER. +.Pp +.Fn 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 +.Sy padding +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. +.Pp +.Fn EVP_CIPHER_key_length +and +.Fn EVP_CIPHER_CTX_key_length +return the key length of a cipher when passed an +.Vt EVP_CIPHER +or +.Vt EVP_CIPHER_CTX +structure. +The constant +.Dv EVP_MAX_KEY_LENGTH +is the maximum key length for all ciphers. +Note: although +.Fn EVP_CIPHER_key_length +is fixed for a given cipher, the value of +.Fn EVP_CIPHER_CTX_key_length +may be different for variable key length ciphers. +.Pp +.Fn 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. +.Pp +.Fn EVP_CIPHER_iv_length +and +.Fn EVP_CIPHER_CTX_iv_length +return the IV length of a cipher when passed an +.Vt EVP_CIPHER +or +.Vt EVP_CIPHER_CTX . +It will return zero if the cipher does not use an IV. +The constant +.Dv EVP_MAX_IV_LENGTH +is the maximum IV length for all ciphers. +.Pp +.Fn EVP_CIPHER_block_size +and +.Fn EVP_CIPHER_CTX_block_size +return the block size of a cipher when passed an +.Vt EVP_CIPHER +or +.Vt EVP_CIPHER_CTX +structure. +The constant +.Dv EVP_MAX_IV_LENGTH +is also the maximum block length for all ciphers. +.Pp +.Fn EVP_CIPHER_type +and +.Fn 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 +.Dv NID_undef . +.Pp +.Fn EVP_CIPHER_CTX_cipher +returns the +.Vt EVP_CIPHER +structure when passed an +.Vt EVP_CIPHER_CTX +structure. +.Pp +.Fn EVP_CIPHER_mode +and +.Fn EVP_CIPHER_CTX_mode +return the block cipher mode: +.Dv EVP_CIPH_ECB_MODE , +.Dv EVP_CIPH_CBC_MODE , +.Dv EVP_CIPH_CFB_MODE , +or +.Dv EVP_CIPH_OFB_MODE . +If the cipher is a stream cipher then +.Dv EVP_CIPH_STREAM_CIPHER +is returned. +.Pp +.Fn 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 +.Fn EVP_EncryptUpdate , +.Fn EVP_DecryptUpdate +calls for example). +This function may fail if the cipher does not have any ASN1 support. +.Pp +.Fn 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 +.Fn EVP_CipherInit +will be called with the IV and key set to +.Dv NULL , +.Fn EVP_CIPHER_asn1_to_param +will be called and finally +.Fn EVP_CipherInit +again with all parameters except the key set to +.Dv 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). +.Pp +.Fn 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. +.Sh RETURN VALUES +.Fn EVP_EncryptInit_ex , +.Fn EVP_EncryptUpdate , +and +.Fn EVP_EncryptFinal_ex +return 1 for success and 0 for failure. +.Pp +.Fn EVP_DecryptInit_ex +and +.Fn EVP_DecryptUpdate +return 1 for success and 0 for failure. +.Fn EVP_DecryptFinal_ex +returns 0 if the decrypt failed or 1 for success. +.Pp +.Fn EVP_CipherInit_ex +and +.Fn EVP_CipherUpdate +return 1 for success and 0 for failure. +.Fn EVP_CipherFinal_ex +returns 0 for a decryption failure or 1 for success. +.Pp +.Fn EVP_CIPHER_CTX_cleanup +returns 1 for success and 0 for failure. +.Pp +.Fn EVP_get_cipherbyname , +.Fn EVP_get_cipherbynid , +and +.Fn EVP_get_cipherbyobj +return an +.Vt EVP_CIPHER +structure or +.Dv NULL +on error. +.Pp +.Fn EVP_CIPHER_nid +and +.Fn EVP_CIPHER_CTX_nid +return a NID. +.Pp +.Fn EVP_CIPHER_block_size +and +.Fn EVP_CIPHER_CTX_block_size +return the block size. +.Pp +.Fn EVP_CIPHER_key_length +and +.Fn EVP_CIPHER_CTX_key_length +return the key length. +.Pp +.Fn EVP_CIPHER_CTX_set_padding +always returns 1. +.Pp +.Fn EVP_CIPHER_iv_length +and +.Fn EVP_CIPHER_CTX_iv_length +return the IV length or zero if the cipher does not use an IV. +.Pp +.Fn EVP_CIPHER_type +and +.Fn EVP_CIPHER_CTX_type +return the NID of the cipher's OBJECT IDENTIFIER or +.Dv NID_undef +if it has no defined OBJECT IDENTIFIER. +.Pp +.Fn EVP_CIPHER_CTX_cipher +returns an +.Vt EVP_CIPHER +structure. +.Pp +.Fn EVP_CIPHER_param_to_asn1 +and +.Fn EVP_CIPHER_asn1_to_param +return 1 for success or 0 for failure. +.Pp +Where possible the EVP 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. +.Pp +PKCS padding works by adding n padding bytes of value n 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 n 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. +.Pp +When decrypting the final block is checked to see if it has the correct +form. +.Pp +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. +.Pp +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. +.Pp +The functions +.Fn EVP_EncryptInit , +.Fn EVP_EncryptFinal , +.Fn EVP_DecryptInit , +.Fn EVP_CipherInit , +and +.Fn EVP_CipherFinal +are obsolete but are retained for compatibility with existing code. +New code should use +.Fn EVP_EncryptInit_ex , +.Fn EVP_EncryptFinal_ex , +.Fn EVP_DecryptInit_ex , +.Fn EVP_DecryptFinal_ex , +.Fn EVP_CipherInit_ex , +and +.Fn EVP_CipherFinal_ex +because they can reuse an existing context without allocating and +freeing it up on each call. +.Sh CIPHER LISTING +All algorithms have a fixed key length unless otherwise stated. +.Bl -tag -width Ds +.It Fn EVP_enc_null void +Null cipher: does nothing. +.It Xo +.Fn EVP_aes_128_cbc void , +.Fn EVP_aes_128_ecb void , +.Fn EVP_aes_128_cfb void , +.Fn EVP_aes_128_ofb void +.Xc +128-bit AES in CBC, ECB, CFB and OFB modes respectively. +.It Xo +.Fn EVP_aes_192_cbc void , +.Fn EVP_aes_192_ecb void , +.Fn EVP_aes_192_cfb void , +.Fn EVP_aes_192_ofb void +.Xc +192-bit AES in CBC, ECB, CFB and OFB modes respectively. +.It Xo +.Fn EVP_aes_256_cbc void , +.Fn EVP_aes_256_ecb void , +.Fn EVP_aes_256_cfb void , +.Fn EVP_aes_256_ofb void +.Xc +256-bit AES in CBC, ECB, CFB and OFB modes respectively. +.It Xo +.Fn EVP_des_cbc void , +.Fn EVP_des_ecb void , +.Fn EVP_des_cfb void , +.Fn EVP_des_ofb void +.Xc +DES in CBC, ECB, CFB and OFB modes respectively. +.It Xo +.Fn EVP_des_ede_cbc void , +.Fn EVP_des_ede void , +.Fn EVP_des_ede_ofb void , +.Fn EVP_des_ede_cfb void +.Xc +Two key triple DES in CBC, ECB, CFB and OFB modes respectively. +.It Xo +.Fn EVP_des_ede3_cbc void , +.Fn EVP_des_ede3 void , +.Fn EVP_des_ede3_ofb void , +.Fn EVP_des_ede3_cfb void +.Xc +Three key triple DES in CBC, ECB, CFB and OFB modes respectively. +.It Fn EVP_desx_cbc void +DESX algorithm in CBC mode. +.It Fn EVP_rc4 void +RC4 stream cipher. +This is a variable key length cipher with default key length 128 bits. +.It Fn EVP_rc4_40 void +RC4 stream cipher with 40 bit key length. +This is obsolete and new code should use +.Fn EVP_rc4 +and the +.Fn EVP_CIPHER_CTX_set_key_length +function. +.It Xo +.Fn EVP_idea_cbc void , +.Fn EVP_idea_ecb void , +.Fn EVP_idea_cfb void , +.Fn EVP_idea_ofb void +.Xc +IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. +.It Xo +.Fn EVP_rc2_cbc void , +.Fn EVP_rc2_ecb void , +.Fn EVP_rc2_cfb void , +.Fn EVP_rc2_ofb void +.Xc +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. +.It Xo +.Fn EVP_rc2_40_cbc void , +.Fn EVP_rc2_64_cbc void +.Xc +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 +.Fn EVP_rc2_cbc , +.Fn EVP_CIPHER_CTX_set_key_length , +and +.Fn EVP_CIPHER_CTX_ctrl +to set the key length and effective key length. +.It Xo +.Fn EVP_bf_cbc void , +.Fn EVP_bf_ecb void , +.Fn EVP_bf_cfb void , +.Fn EVP_bf_ofb void +.Xc +Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes +respectively. +This is a variable key length cipher. +.It Xo +.Fn EVP_cast5_cbc void , +.Fn EVP_cast5_ecb void , +.Fn EVP_cast5_cfb void , +.Fn EVP_cast5_ofb void +.Xc +CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. +This is a variable key length cipher. +.It Xo +.Fn EVP_rc5_32_12_16_cbc void , +.Fn EVP_rc5_32_12_16_ecb void , +.Fn EVP_rc5_32_12_16_cfb void , +.Fn EVP_rc5_32_12_16_ofb void +.Xc +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. +.El +.Sh EXAMPLES +Get the number of rounds used in RC5: +.Bd -literal +int nrounds; +EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); +.Ed +.Pp +Get the RC2 effective key length: +.Bd -literal +int key_bits; +EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); +.Ed +.Pp +Set the number of rounds used in RC5: +.Bd -literal +int nrounds; +EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); +.Ed +.Pp +Set the effective key length used in RC2: +.Bd -literal +int key_bits; +EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); +.Ed +.Pp +Encrypt a string using blowfish: +.Bd -literal +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; +} +.Ed +.Pp +The ciphertext from the above example can be decrypted using the +.Xr openssl 1 +utility with the command line: +.Bd -literal +openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F \e + -iv 0102030405060708 -d +.Ed +.Pp +General encryption, decryption function example using FILE I/O and RC2 +with an 80 bit key: +.Bd -literal +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; +} +.Ed +.Sh SEE ALSO +.Xr evp 3 +.Sh HISTORY +.Fn EVP_CIPHER_CTX_init , +.Fn EVP_EncryptInit_ex , +.Fn EVP_EncryptFinal_ex , +.Fn EVP_DecryptInit_ex , +.Fn EVP_DecryptFinal_ex , +.Fn EVP_CipherInit_ex , +.Fn EVP_CipherFinal_ex , +and +.Fn EVP_CIPHER_CTX_set_padding +appeared in OpenSSL 0.9.7. +.Sh 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. +.Pp +.Dv EVP_MAX_KEY_LENGTH +and +.Dv 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 +.Dv EVP_MAX_KEY_LENGTH +bytes. +.Pp +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. diff --git a/src/lib/libcrypto/man/EVP_OpenInit.3 b/src/lib/libcrypto/man/EVP_OpenInit.3 new file mode 100644 index 0000000000..92873ac453 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_OpenInit.3 @@ -0,0 +1,98 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_OPENINIT 3 +.Os +.Sh NAME +.Nm EVP_OpenInit , +.Nm EVP_OpenUpdate , +.Nm EVP_OpenFinal +.Nd EVP envelope decryption +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_OpenInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "EVP_CIPHER *type" +.Fa "unsigned char *ek" +.Fa "int ekl" +.Fa "unsigned char *iv" +.Fa "EVP_PKEY *priv" +.Fc +.Ft int +.Fo EVP_OpenUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_OpenFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Sh 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. +.Pp +.Fn EVP_OpenInit +initializes a cipher context +.Fa ctx +for decryption with cipher +.Fa type . +It decrypts the encrypted symmetric key of length +.Fa ekl +bytes passed in the +.Fa ek +parameter using the private key +.Fa priv . +The IV is supplied in the +.Fa iv +parameter. +.Pp +.Fn EVP_OpenUpdate +and +.Fn EVP_OpenFinal +have exactly the same properties as the +.Xr EVP_DecryptUpdate 3 +and +.Xr EVP_DecryptFinal 3 +routines. +.Pp +It is possible to call +.Fn EVP_OpenInit +twice in the same way as +.Xr EVP_DecryptInit 3 . +The first call should have +.Fa priv +set to +.Dv NULL +and (after setting any cipher parameters) it should be +called again with +.Fa type +set to +.Dv NULL . +.Pp +If the cipher passed in the +.Fa type +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. +.Sh RETURN VALUES +.Fn EVP_OpenInit +returns 0 on error or a non zero integer (actually the recovered secret +key size) if successful. +.Pp +.Fn EVP_OpenUpdate +returns 1 for success or 0 for failure. +.Pp +.Fn EVP_OpenFinal +returns 0 if the decrypt failed or 1 for success. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_SealInit 3 , +.Xr rand 3 diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 new file mode 100644 index 0000000000..5b1b94653a --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 @@ -0,0 +1,245 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_CTX_CTRL 3 +.Os +.Sh NAME +.Nm EVP_PKEY_CTX_ctrl , +.Nm EVP_PKEY_CTX_ctrl_str , +.Nm EVP_PKEY_get_default_digest_nid , +.Nm EVP_PKEY_CTX_set_signature_md , +.Nm EVP_PKEY_CTX_set_rsa_padding , +.Nm EVP_PKEY_CTX_set_rsa_pss_saltlen , +.Nm EVP_PKEY_CTX_set_rsa_rsa_keygen_bits , +.Nm EVP_PKEY_CTX_set_rsa_keygen_pubexp , +.Nm EVP_PKEY_CTX_set_dsa_paramgen_bits , +.Nm EVP_PKEY_CTX_set_dh_paramgen_prime_len , +.Nm EVP_PKEY_CTX_set_dh_paramgen_generator , +.Nm EVP_PKEY_CTX_set_ec_paramgen_curve_nid +.Nd algorithm specific control operations +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_CTX_ctrl +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int keytype" +.Fa "int optype" +.Fa "int cmd" +.Fa "int p1" +.Fa "void *p2" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_ctrl_str +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const char *type" +.Fa "const char *value" +.Fc +.Ft int +.Fo EVP_PKEY_get_default_digest_nid +.Fa "EVP_PKEY *pkey" +.Fa "int *pnid" +.Fc +.In openssl/rsa.h +.Ft int +.Fo EVP_PKEY_CTX_set_signature_md +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const EVP_MD *md" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_padding +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int pad" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_pss_saltlen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_rsa_keygen_bits +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int mbits" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_rsa_keygen_pubexp +.Fa "EVP_PKEY_CTX *ctx" +.Fa "BIGNUM *pubexp" +.Fc +.In openssl/dsa.h +.Ft int +.Fo EVP_PKEY_CTX_set_dsa_paramgen_bits +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int nbits" +.Fc +.In openssl/dh.h +.Ft int +.Fo EVP_PKEY_CTX_set_dh_paramgen_prime_len +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int len" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_set_dh_paramgen_generator +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int gen" +.Fc +.In openssl/ec.h +.Ft int +.Fo EVP_PKEY_CTX_set_ec_paramgen_curve_nid +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int nid" +.Fc +.Sh DESCRIPTION +The function +.Fn EVP_PKEY_CTX_ctrl +sends a control operation to the context +.Fa ctx . +The key type used must match +.Fa keytype +if it is not -1. +The parameter +.Fa optype +is a mask indicating which operations the control can be applied to. +The control command is indicated in +.Fa cmd +and any additional arguments in +.Fa p1 +and +.Fa p2 . +.Pp +Applications will not normally call +.Fn EVP_PKEY_CTX_ctrl +directly but will instead call one of the algorithm specific macros +below. +.Pp +The function +.Fn EVP_PKEY_CTX_ctrl_str +allows an application to send an algorithm specific control operation to +a context +.Fa ctx +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 +.Xr openssl 1 +utility command line pages for the option +.Fl pkeyopt +which is supported by the +.Cm pkeyutl , +.Cm genpkey , +and +.Cm req +commands. +.Pp +All the remaining "functions" are implemented as macros. +.Pp +The +.Fn 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. +.Pp +The macro +.Fn EVP_PKEY_CTX_set_rsa_padding +sets the RSA padding mode for +.Fa ctx . +The +.Fa pad +parameter can take the value +.Dv RSA_PKCS1_PADDING +for PKCS#1 padding, +.Dv RSA_SSLV23_PADDING +for SSLv23 padding, +.Dv RSA_NO_PADDING +for no padding, +.Dv RSA_PKCS1_OAEP_PADDING +for OAEP padding (encrypt and decrypt only), +.Dv RSA_X931_PADDING +for X9.31 padding (signature operations only) and +.Dv RSA_PKCS1_PSS_PADDING +(sign and verify only). +.Pp +Two RSA padding modes behave differently if +.Fn 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. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_pss_saltlen +macro sets the RSA PSS salt length to +.Fa len +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 PSS block structure. +If this macro is not called a salt length value of -2 is used by +default. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_rsa_keygen_bits +macro sets the RSA key length for RSA key generation to +.Fa mbits . +If not specified, 1024 bits is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_rsa_keygen_pubexp +macro sets the public exponent value for RSA key generation to +.Fa pubexp . +Currently, it should be an odd integer. +The +.Fa pubexp +pointer is used internally by this function, so it should not be modified +or freed after the call. +If this macro is not called, then 65537 is used. +.Pp +The macro +.Fn EVP_PKEY_CTX_set_dsa_paramgen_bits +sets the number of bits used for DSA parameter generation to +.Fa nbits . +If not specified, 1024 is used. +.Pp +The macro +.Fn EVP_PKEY_CTX_set_dh_paramgen_prime_len +sets the length of the DH prime parameter +.Fa len +for DH parameter generation. +If this macro is not called, then 1024 is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_dh_paramgen_generator +macro sets DH generator to +.Fa gen +for DH parameter generation. +If not specified, 2 is used. +.Pp +The +.Fn EVP_PKEY_CTX_set_ec_paramgen_curve_nid +sets the EC curve for EC parameter generation to +.Fa nid . +For EC parameter generation, this macro must be called or an error occurs +because there is no default curve. +.Sh RETURN VALUES +.Fn 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. +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 new file mode 100644 index 0000000000..c08db1eb21 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_CTX_new.3 @@ -0,0 +1,85 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_CTX_NEW 3 +.Os +.Sh NAME +.Nm EVP_PKEY_CTX_new , +.Nm EVP_PKEY_CTX_new_id , +.Nm EVP_PKEY_CTX_dup , +.Nm EVP_PKEY_CTX_free +.Nd public key algorithm context functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft EVP_PKEY_CTX * +.Fo EVP_PKEY_CTX_new +.Fa "EVP_PKEY *pkey" +.Fa "ENGINE *e" +.Fc +.Ft EVP_PKEY_CTX * +.Fo EVP_PKEY_CTX_new_id +.Fa "int id" +.Fa "ENGINE *e" +.Fc +.Ft EVP_PKEY_CTX * +.Fo EVP_PKEY_CTX_dup +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_free +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_CTX_new +function allocates a public key algorithm context using the algorithm +specified in +.Fa pkey +and the +.Vt ENGINE +.Fa e . +.Pp +The +.Fn EVP_PKEY_CTX_new_id +function allocates a public key algorithm context using the algorithm +specified by +.Fa id +and +.Vt ENGINE +.Fa e . +It is normally used when no +.Vt EVP_PKEY +structure is associated with the operations, for example during +parameter generation of key generation for some algorithms. +.Pp +.Fn EVP_PKEY_CTX_dup +duplicates the context +.Fa ctx . +.Pp +.Fn EVP_PKEY_CTX_free +frees up the context +.Fa ctx . +.Sh RETURN VALUES +.Fn EVP_PKEY_CTX_new , +.Fn EVP_PKEY_CTX_new_id , +.Fn EVP_PKEY_CTX_dup +returns either the newly allocated +.Vt EVP_PKEY_CTX +structure of +.Dv NULL +if an error occurred. +.Pp +.Fn EVP_PKEY_CTX_free +does not return a value. +.Sh SEE ALSO +.Xr EVP_PKEY_new 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. +.Sh CAVEATS +The +.Vt EVP_PKEY_CTX +structure is an opaque public key algorithm context used by the OpenSSL +high level public key API. +Contexts +.Sy MUST NOT +be shared between threads. +It is not permissible to use the same context simultaneously in two +threads. diff --git a/src/lib/libcrypto/man/EVP_PKEY_cmp.3 b/src/lib/libcrypto/man/EVP_PKEY_cmp.3 new file mode 100644 index 0000000000..a3c3ba4fec --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_cmp.3 @@ -0,0 +1,92 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_CMP 3 +.Os +.Sh NAME +.Nm EVP_PKEY_copy_parameters , +.Nm EVP_PKEY_missing_parameters , +.Nm EVP_PKEY_cmp_parameters , +.Nm EVP_PKEY_cmp +.Nd public key parameter and comparison functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_missing_parameters +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_copy_parameters +.Fa "EVP_PKEY *to" +.Fa "const EVP_PKEY *from" +.Fc +.Ft int +.Fo EVP_PKEY_cmp_parameters +.Fa "const EVP_PKEY *a" +.Fa "const EVP_PKEY *b" +.Fc +.Ft int +.Fo EVP_PKEY_cmp +.Fa "const EVP_PKEY *a" +.Fa "const EVP_PKEY *b" +.Fc +.Sh DESCRIPTION +The function +.Fn EVP_PKEY_missing_parameters +returns 1 if the public key parameters of +.Fa pkey +are missing and 0 if they are present or the algorithm doesn't use +parameters. +.Pp +The function +.Fn EVP_PKEY_copy_parameters +copies the parameters from key +.Fa from +to key +.Fa to . +.Pp +The function +.Fn EVP_PKEY_cmp_parameters +compares the parameters of keys +.Fa a +and +.Fa b . +.Pp +The function +.Fn EVP_PKEY_cmp +compares the public key components and parameters (if present) of keys +.Fa a +and +.Fa b . +.Pp +The main purpose of the functions +.Fn EVP_PKEY_missing_parameters +and +.Fn 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. +.Pp +Since OpenSSL private keys contain public key components too, the +function +.Fn EVP_PKEY_cmp +can also be used to determine if a private key matches a public key. +.Sh RETURN VALUES +The function +.Fn EVP_PKEY_missing_parameters +returns 1 if the public key parameters of +.Fa pkey +are missing and 0 if they are present or the algorithm doesn't use +parameters. +.Pp +The function +.Fn EVP_PKEY_copy_parameters +returns 1 for success and 0 for failure. +.Pp +The function +.Fn EVP_PKEY_cmp_parameters +and +.Fn 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. +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_keygen 3 diff --git a/src/lib/libcrypto/man/EVP_PKEY_decrypt.3 b/src/lib/libcrypto/man/EVP_PKEY_decrypt.3 new file mode 100644 index 0000000000..28c343838d --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_decrypt.3 @@ -0,0 +1,117 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_DECRYPT 3 +.Os +.Sh NAME +.Nm EVP_PKEY_decrypt_init , +.Nm EVP_PKEY_decrypt +.Nd decrypt using a public key algorithm +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_decrypt_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_decrypt +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *out" +.Fa "size_t *outlen" +.Fa "const unsigned char *in" +.Fa "size_t inlen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_decrypt_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a decryption operation. +.Pp +The +.Fn EVP_PKEY_decrypt +function performs a public key decryption operation using +.Fa ctx . +The data to be decrypted is specified using the +.Fa in +and +.Fa inlen +parameters. +If +.Fa out +is +.Dv NULL +then the maximum size of the output buffer is written to the +.Fa outlen +parameter. +If +.Fa out +is not +.Dv NULL +then before the call the +.Fa outlen +parameter should contain the length of the +.Fa out +buffer, if the call is successful the decrypted data is written to +.Fa out +and the amount of data written to +.Fa outlen . +.Pp +After the call to +.Fn EVP_PKEY_decrypt_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_decrypt +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_decrypt_init +and +.Fn 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. +.Sh EXAMPLE +Decrypt data using OAEP (for RSA keys): +.Bd -literal +#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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_derive.3 b/src/lib/libcrypto/man/EVP_PKEY_derive.3 new file mode 100644 index 0000000000..e67280cf20 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_derive.3 @@ -0,0 +1,120 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_DERIVE 3 +.Os +.Sh NAME +.Nm EVP_PKEY_derive_init , +.Nm EVP_PKEY_derive_set_peer , +.Nm EVP_PKEY_derive +.Nd derive public key algorithm shared secret +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_derive_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_derive_set_peer +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY *peer" +.Fc +.Ft int +.Fo EVP_PKEY_derive +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *key" +.Fa "size_t *keylen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_derive_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for shared secret derivation. +.Pp +The +.Fn EVP_PKEY_derive_set_peer +function sets the peer key: this will normally be a public key. +.Pp +The +.Fn EVP_PKEY_derive +derives a shared secret using +.Fa ctx . +If +.Fa key +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa keylen +parameter. +If +.Fa key +is not +.Dv NULL +then before the call the +.Fa keylen +parameter should contain the length of the +.Fa key +buffer. +If the call is successful, the shared secret is written to +.Fa key +and the amount of data written to +.Fa keylen . +.Pp +After the call to +.Fn EVP_PKEY_derive_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_derive +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_derive_init +and +.Fn 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. +.Sh EXAMPLES +Derive shared secret (for example DH or EC keys): +.Bd -literal +#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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_encrypt.3 b/src/lib/libcrypto/man/EVP_PKEY_encrypt.3 new file mode 100644 index 0000000000..bda37ef160 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_encrypt.3 @@ -0,0 +1,117 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_ENCRYPT 3 +.Os +.Sh NAME +.Nm EVP_PKEY_encrypt_init , +.Nm EVP_PKEY_encrypt +.Nd encrypt using a public key algorithm +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_encrypt_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_encrypt +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *out" +.Fa "size_t *outlen" +.Fa "const unsigned char *in" +.Fa "size_t inlen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_encrypt_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for an encryption operation. +.Pp +The +.Fn EVP_PKEY_encrypt +function performs a public key encryption operation using +.Fa ctx . +The data to be encrypted is specified using the +.Fa in +and +.Fa inlen +parameters. +If +.Fa out +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa outlen +parameter. +If +.Fa out +is not +.Dv NULL , +then before the call the +.Fa outlen +parameter should contain the length of the +.Fa out +buffer, if the call is successful the encrypted data is written to +.Fa out +and the amount of data written to +.Fa outlen . +.Pp +After the call to +.Fn EVP_PKEY_encrypt_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_encrypt +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_encrypt_init +and +.Fn 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. +.Sh EXAMPLES +Encrypt data using OAEP (for RSA keys): +.Bd -literal +#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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_get_default_digest.3 b/src/lib/libcrypto/man/EVP_PKEY_get_default_digest.3 new file mode 100644 index 0000000000..2266adadf3 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_get_default_digest.3 @@ -0,0 +1,39 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_GET_DEFAULT_DIGEST 3 +.Os +.Sh NAME +.Nm EVP_PKEY_get_default_digest_nid +.Nd get default signature digest +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_get_default_digest_nid +.Fa "EVP_PKEY *pkey" +.Fa "int *pnid" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_get_default_digest_nid +function sets +.Fa pnid +to the default message digest NID for the public key signature +operations associated with key +.Fa pkey . +.Pp +For all current standard OpenSSL public key algorithms, SHA1 is returned. +.Sh RETURN VALUES +The +.Fn 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 cannot 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. +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +This function was first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_keygen.3 b/src/lib/libcrypto/man/EVP_PKEY_keygen.3 new file mode 100644 index 0000000000..8a5c7be0c6 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_keygen.3 @@ -0,0 +1,235 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_KEYGEN 3 +.Os +.Sh NAME +.Nm EVP_PKEY_keygen_init , +.Nm EVP_PKEY_keygen , +.Nm EVP_PKEY_paramgen_init , +.Nm EVP_PKEY_paramgen , +.Nm EVP_PKEY_CTX_set_cb , +.Nm EVP_PKEY_CTX_get_cb , +.Nm EVP_PKEY_CTX_get_keygen_info , +.Nm EVP_PKEY_CTX_set_app_data , +.Nm EVP_PKEY_CTX_get_app_data +.Nd key and parameter generation functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_keygen_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_keygen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY **ppkey" +.Fc +.Ft int +.Fo EVP_PKEY_paramgen_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_paramgen +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY **ppkey" +.Fc +.Ft typedef int +.Fo EVP_PKEY_gen_cb +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_set_cb +.Fa "EVP_PKEY_CTX *ctx" +.Fa "EVP_PKEY_gen_cb *cb" +.Fc +.Ft EVP_PKEY_gen_cb * +.Fo EVP_PKEY_CTX_get_cb +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_CTX_get_keygen_info +.Fa "EVP_PKEY_CTX *ctx" +.Fa "int idx" +.Fc +.Ft void +.Fo EVP_PKEY_CTX_set_app_data +.Fa "EVP_PKEY_CTX *ctx" +.Fa "void *data" +.Fc +.Ft void * +.Fo EVP_PKEY_CTX_get_app_data +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_keygen_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a key generation operation. +.Pp +The +.Fn EVP_PKEY_keygen +function performs a key generation operation, the generated key is +written to +.Fa ppkey . +.Pp +The functions +.Fn EVP_PKEY_paramgen_init +and +.Fn EVP_PKEY_paramgen +are similar except parameters are generated. +.Pp +The function +.Fn EVP_PKEY_CTX_set_cb +sets the key or parameter generation callback to +.Fa cb . +The function +.Fn EVP_PKEY_CTX_get_cb +returns the key or parameter generation callback. +.Pp +The function +.Fn EVP_PKEY_CTX_get_keygen_info +returns parameters associated with the generation operation. +If +.Fa idx +is -1, the total number of parameters available is returned. +Any non negative value returns the value of that parameter. +.Fn EVP_PKEY_CTX_get_keygen_info +with a non-negative value for +.Fa idx +should only be called within the generation callback. +.Pp +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. +.Pp +The functions +.Fn EVP_PKEY_CTX_set_app_data +and +.Fn 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". +.Pp +After the call to +.Fn EVP_PKEY_keygen_init +or +.Fn EVP_PKEY_paramgen_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The functions +.Fn EVP_PKEY_keygen +and +.Fn EVP_PKEY_paramgen +can be called more than once on the same context if several operations +are performed using the same parameters. +.Pp +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. +.Pp +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 +.Vt EVP_PKEY +structure. +.Pp +In OpenSSL, an +.Vt 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. +.Sh RETURN VALUES +.Fn EVP_PKEY_keygen_init , +.Fn EVP_PKEY_paramgen_init , +.Fn EVP_PKEY_keygen , +and +.Fn 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. +.Sh EXAMPLES +Generate a 2048 bit RSA key: +.Bd -literal +#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 */ +.Ed +.Pp +Generate a key from a set of parameters: +.Bd -literal +#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 */ +.Ed +.Pp +Example of generation callback for OpenSSL public key implementations: +.Bd -literal +/* 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='\en'; + BIO_write(b,&c,1); + (void)BIO_flush(b); + return 1; +} +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_new.3 b/src/lib/libcrypto/man/EVP_PKEY_new.3 new file mode 100644 index 0000000000..155ca9ad24 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_new.3 @@ -0,0 +1,44 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_NEW 3 +.Os +.Sh NAME +.Nm EVP_PKEY_new , +.Nm EVP_PKEY_free +.Nd private key allocation functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft EVP_PKEY * +.Fn EVP_PKEY_new void +.Ft void +.Fo EVP_PKEY_free +.Fa "EVP_PKEY *key" +.Fc +.Sh DESCRIPTION +The +.Vt EVP_PKEY +structure is used by various OpenSSL functions which require a general +private key without reference to any particular algorithm. +.Pp +The +.Fn EVP_PKEY_new +function allocates an empty +.Vt EVP_PKEY +structure. +To add a private key to it, use the functions described in +.Xr EVP_PKEY_set1_RSA 3 . +.Pp +.Fn EVP_PKEY_free +frees up the private key +.Fa key . +.Sh RETURN VALUES +.Fn EVP_PKEY_new +returns either the newly allocated +.Vt EVP_PKEY +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn EVP_PKEY_free +does not return a value. +.Sh SEE ALSO +.Xr EVP_PKEY_set1_RSA 3 diff --git a/src/lib/libcrypto/man/EVP_PKEY_print_private.3 b/src/lib/libcrypto/man/EVP_PKEY_print_private.3 new file mode 100644 index 0000000000..d1f627c6a0 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_print_private.3 @@ -0,0 +1,76 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_PRINT_PRIVATE 3 +.Os +.Sh NAME +.Nm EVP_PKEY_print_public , +.Nm EVP_PKEY_print_private , +.Nm EVP_PKEY_print_params +.Nd public key algorithm printing routines +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_print_public +.Fa "BIO *out" +.Fa "const EVP_PKEY *pkey" +.Fa "int indent" +.Fa "ASN1_PCTX *pctx" +.Fc +.Ft int +.Fo EVP_PKEY_print_private +.Fa "BIO *out" +.Fa "const EVP_PKEY *pkey" +.Fa "int indent" +.Fa "ASN1_PCTX *pctx" +.Fc +.Ft int +.Fo EVP_PKEY_print_params +.Fa "BIO *out" +.Fa "const EVP_PKEY *pkey" +.Fa "int indent" +.Fa "ASN1_PCTX *pctx" +.Fc +.Sh DESCRIPTION +The functions +.Fn EVP_PKEY_print_public , +.Fn EVP_PKEY_print_private , +and +.Fn EVP_PKEY_print_params +print out the public, private or parameter components of key +.Fa pkey , +respectively. +The key is sent to +.Vt BIO +.Fa out +in human readable form. +The parameter +.Fa indent +indicates how far the printout should be indented. +.Pp +The +.Fa pctx +parameter allows the print output to be finely tuned by using ASN1 +printing options. +If +.Fa pctx +is set to +.Dv NULL , +then default values will be used. +Currently, no public key algorithms include any options in the +.Fa pctx +parameter. +.Pp +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 +.Fn EVP_PKEY_print_private +will only print the public components. +.Sh 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. +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_keygen 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 b/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 new file mode 100644 index 0000000000..986918dc2f --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_set1_RSA.3 @@ -0,0 +1,171 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_SET1_RSA 3 +.Os +.Sh NAME +.Nm EVP_PKEY_set1_RSA , +.Nm EVP_PKEY_set1_DSA , +.Nm EVP_PKEY_set1_DH , +.Nm EVP_PKEY_set1_EC_KEY , +.Nm EVP_PKEY_get1_RSA , +.Nm EVP_PKEY_get1_DSA , +.Nm EVP_PKEY_get1_DH , +.Nm EVP_PKEY_get1_EC_KEY , +.Nm EVP_PKEY_assign_RSA , +.Nm EVP_PKEY_assign_DSA , +.Nm EVP_PKEY_assign_DH , +.Nm EVP_PKEY_assign_EC_KEY , +.Nm EVP_PKEY_type +.Nd EVP_PKEY assignment functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_set1_RSA +.Fa "EVP_PKEY *pkey" +.Fa "RSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_set1_DSA +.Fa "EVP_PKEY *pkey" +.Fa "DSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_set1_DH +.Fa "EVP_PKEY *pkey" +.Fa "DH *key" +.Fc +.Ft int +.Fo EVP_PKEY_set1_EC_KEY +.Fa "EVP_PKEY *pkey" +.Fa "EC_KEY *key" +.Fc +.Ft RSA * +.Fo EVP_PKEY_get1_RSA +.Fa "EVP_PKEY *pkey" +.Fc +.Ft DSA * +.Fo EVP_PKEY_get1_DSA +.Fa "EVP_PKEY *pkey" +.Fc +.Ft DH * +.Fo EVP_PKEY_get1_DH +.Fa "EVP_PKEY *pkey" +.Fc +.Ft EC_KEY * +.Fo EVP_PKEY_get1_EC_KEY +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_assign_RSA +.Fa "EVP_PKEY *pkey" +.Fa "RSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign_DSA +.Fa "EVP_PKEY *pkey" +.Fa "DSA *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign_DH +.Fa "EVP_PKEY *pkey" +.Fa "DH *key" +.Fc +.Ft int +.Fo EVP_PKEY_assign_EC_KEY +.Fa "EVP_PKEY *pkey" +.Fa "EC_KEY *key" +.Fc +.Ft int +.Fo EVP_PKEY_type +.Fa "int type" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_set1_RSA , +.Fn EVP_PKEY_set1_DSA , +.Fn EVP_PKEY_set1_DH , +and +.Fn EVP_PKEY_set1_EC_KEY +set the key referenced by +.Fa pkey +to +.Fa key . +.Pp +.Fn EVP_PKEY_get1_RSA , +.Fn EVP_PKEY_get1_DSA , +.Fn EVP_PKEY_get1_DH , +and +.Fn EVP_PKEY_get1_EC_KEY +return the key referenced in +.Fa pkey +or +.Dv NULL +if the key is not of the correct type. +.Pp +.Fn EVP_PKEY_assign_RSA , +.Fn EVP_PKEY_assign_DSA , +.Fn EVP_PKEY_assign_DH , +and +.Fn EVP_PKEY_assign_EC_KEY +also set the referenced key to +.Fa key ; +however these use the supplied +.Fa key +internally and so +.Fa key +will be freed when the parent +.Fa pkey +is freed. +.Pp +.Fn EVP_PKEY_type +returns the type of key corresponding to the value +.Fa type . +The type of a key can be obtained with +.Fn EVP_PKEY_type pkey->type . +The return value will be +.Dv EVP_PKEY_RSA , +.Dv EVP_PKEY_DSA , +.Dv EVP_PKEY_DH , +or +.Dv EVP_PKEY_EC +for the corresponding key types or +.Dv NID_undef +if the key type is unassigned. +.Pp +In accordance with the OpenSSL naming convention, the key obtained from +or assigned to +.Fa pkey +using the +.Sy 1 +functions must be freed as well as +.Fa pkey . +.Pp +.Fn EVP_PKEY_assign_RSA , +.Fn EVP_PKEY_assign_DSA , +.Fn EVP_PKEY_assign_DH , +and +.Fn EVP_PKEY_assign_EC_KEY +are implemented as macros. +.Sh RETURN VALUES +.Fn EVP_PKEY_set1_RSA , +.Fn EVP_PKEY_set1_DSA , +.Fn EVP_PKEY_set1_DH , +and +.Fn EVP_PKEY_set1_EC_KEY +return 1 for success or 0 for failure. +.Pp +.Fn EVP_PKEY_get1_RSA , +.Fn EVP_PKEY_get1_DSA , +.Fn EVP_PKEY_get1_DH , +and +.Fn EVP_PKEY_get1_EC_KEY +return the referenced key or +.Dv NULL +if an error occurred. +.Pp +.Fn EVP_PKEY_assign_RSA , +.Fn EVP_PKEY_assign_DSA , +.Fn EVP_PKEY_assign_DH , +and +.Fn EVP_PKEY_assign_EC_KEY +return 1 for success and 0 for failure. +.Sh SEE ALSO +.Xr EVP_PKEY_new 3 diff --git a/src/lib/libcrypto/man/EVP_PKEY_sign.3 b/src/lib/libcrypto/man/EVP_PKEY_sign.3 new file mode 100644 index 0000000000..f8e4da7a9d --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_sign.3 @@ -0,0 +1,120 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_SIGN 3 +.Os +.Sh NAME +.Nm EVP_PKEY_sign_init , +.Nm EVP_PKEY_sign +.Nd sign using a public key algorithm +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_sign_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_sign +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *sig" +.Fa "size_t *siglen" +.Fa "const unsigned char *tbs" +.Fa "size_t tbslen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_sign_init +function initializes a public key algorithm context using the key +.Fa ctx->pkey +for a signing operation. +.Pp +The +.Fn EVP_PKEY_sign +function performs a public key signing operation using +.Fa ctx . +The data to be signed is specified using the +.Fa tbs +and +.Fa tbslen +parameters. +If +.Fa sig +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa siglen +parameter. +If +.Fa sig +is not +.Dv NULL , +then before the call the +.Fa siglen +parameter should contain the length of the +.Fa sig +buffer. +If the call is successful the signature is written to +.Fa sig +and the amount of data written to +.Fa siglen . +.Pp +After the call to +.Fn EVP_PKEY_sign_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_sign +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_sign_init +and +.Fn 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. +.Sh EXAMPLES +Sign data using RSA with PKCS#1 padding and SHA256 digest: +.Bd -literal +#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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_verify.3 b/src/lib/libcrypto/man/EVP_PKEY_verify.3 new file mode 100644 index 0000000000..bec3283349 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_verify.3 @@ -0,0 +1,109 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_VERIFY 3 +.Os +.Sh NAME +.Nm EVP_PKEY_verify_init , +.Nm EVP_PKEY_verify +.Nd signature verification using a public key algorithm +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_verify_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_verify +.Fa "EVP_PKEY_CTX *ctx" +.Fa "const unsigned char *sig" +.Fa "size_t siglen" +.Fa "const unsigned char *tbs" +.Fa "size_t tbslen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_verify_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a signature verification operation. +.Pp +The +.Fn EVP_PKEY_verify +function performs a public key verification operation using +.Fa ctx . +The signature is specified using the +.Fa sig +and +.Fa siglen +parameters. +The verified data (i.e. the data believed originally signed) is +specified using the +.Fa tbs +and +.Fa tbslen +parameters. +.Pp +After the call to +.Fn EVP_PKEY_verify_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_verify +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_verify_init +and +.Fn EVP_PKEY_verify +return 1 if the verification was successful and 0 if it failed. +Unlike other functions the return value 0 from +.Fn EVP_PKEY_verify +only indicates that the signature did not verify successfully. +That is, +.Fa tbs +did not match the original data or the signature was of invalid form. +It is not an indication of a more serious error. +.Pp +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. +.Sh EXAMPLES +Verify signature using PKCS#1 and SHA256 digest: +.Bd -literal +#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. + */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify_recover 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_PKEY_verify_recover.3 b/src/lib/libcrypto/man/EVP_PKEY_verify_recover.3 new file mode 100644 index 0000000000..fc26152ae6 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_PKEY_verify_recover.3 @@ -0,0 +1,131 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_PKEY_VERIFY_RECOVER 3 +.Os +.Sh NAME +.Nm EVP_PKEY_verify_recover_init , +.Nm EVP_PKEY_verify_recover +.Nd recover signature using a public key algorithm +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_verify_recover_init +.Fa "EVP_PKEY_CTX *ctx" +.Fc +.Ft int +.Fo EVP_PKEY_verify_recover +.Fa "EVP_PKEY_CTX *ctx" +.Fa "unsigned char *rout" +.Fa "size_t *routlen" +.Fa "const unsigned char *sig" +.Fa "size_t siglen" +.Fc +.Sh DESCRIPTION +The +.Fn EVP_PKEY_verify_recover_init +function initializes a public key algorithm context using key +.Fa ctx->pkey +for a verify recover operation. +.Pp +The +.Fn EVP_PKEY_verify_recover +function recovers signed data using +.Fa ctx . +The signature is specified using the +.Fa sig +and +.Fa siglen +parameters. +If +.Fa rout +is +.Dv NULL , +then the maximum size of the output buffer is written to the +.Fa routlen +parameter. +If +.Fa rout +is not +.Dv NULL , +then before the call the +.Fa routlen +parameter should contain the length of the +.Fa rout +buffer. +If the call is successful, recovered data is written to +.Fa rout +and the amount of data written to +.Fa routlen . +.Pp +Normally an application is only interested in whether a signature +verification operation is successful. +In those cases, the +.Xr EVP_verify 3 +function should be used. +.Pp +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). +.Pp +After the call to +.Fn EVP_PKEY_verify_recover_init , +algorithm specific control operations can be performed to set any +appropriate parameters for the operation. +.Pp +The function +.Fn EVP_PKEY_verify_recover +can be called more than once on the same context if several operations +are performed using the same parameters. +.Sh RETURN VALUES +.Fn EVP_PKEY_verify_recover_init +and +.Fn 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. +.Sh EXAMPLES +Recover digest originally signed using PKCS#1 and SHA256 digest: +.Bd -literal +#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 */ +.Ed +.Sh SEE ALSO +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_derive 3 +.Sh HISTORY +These functions were first added to OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/EVP_SealInit.3 b/src/lib/libcrypto/man/EVP_SealInit.3 new file mode 100644 index 0000000000..9511111486 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_SealInit.3 @@ -0,0 +1,131 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_SEALINIT 3 +.Os +.Sh NAME +.Nm EVP_SealInit , +.Nm EVP_SealUpdate , +.Nm EVP_SealFinal +.Nd EVP envelope encryption +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_SealInit +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "const EVP_CIPHER *type" +.Fa "unsigned char **ek" +.Fa "int *ekl" +.Fa "unsigned char *iv" +.Fa "EVP_PKEY **pubk" +.Fa "int npubk" +.Fc +.Ft int +.Fo EVP_SealUpdate +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fa "unsigned char *in" +.Fa "int inl" +.Fc +.Ft int +.Fo EVP_SealFinal +.Fa "EVP_CIPHER_CTX *ctx" +.Fa "unsigned char *out" +.Fa "int *outl" +.Fc +.Sh 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. +.Pp +.Fn EVP_SealInit +initializes a cipher context +.Fa ctx +for encryption with cipher +.Fa type +using a random secret key and IV. +.Fa type +is normally supplied by a function such as +.Fn EVP_aes_256_cbc 3 ; +see +.Xr EVP_EncryptInit 3 +for details. +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. +.Fa ek +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 +.Fa ek[i] +must have room for +.Fn EVP_PKEY_size pubk[i] +bytes. +The actual size of each encrypted secret key is written to the array +.Fa ekl . +.Fa pubk +is an array of +.Fa npubk +public keys. +.Pp +The +.Fa iv +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) +.Fn EVP_CIPHER_iv_length type . +.Pp +If the cipher does not require an IV then the +.Fa iv +parameter is ignored and can be +.Dv NULL . +.Pp +.Fn EVP_SealUpdate +and +.Fn EVP_SealFinal +have exactly the same properties as the +.Xr EVP_EncryptUpdate 3 +and +.Xr EVP_EncryptFinal 3 +routines. +.Pp +The public key must be RSA because it is the only OpenSSL public key +algorithm that supports key transport. +.Pp +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. +.Pp +It is possible to call +.Fn EVP_SealInit +twice in the same way as +.Xr EVP_EncryptInit 3 . +The first call should have +.Fa npubk +set to 0 and (after setting any cipher parameters) it should be called +again with +.Fa type +set to NULL. +.Sh RETURN VALUES +.Fn EVP_SealInit +returns 0 on error or +.Fa npubk +if successful. +.Pp +.Fn EVP_SealUpdate +and +.Fn EVP_SealFinal +return 1 for success and 0 for failure. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_OpenInit 3 , +.Xr rand 3 +.Sh HISTORY +.Fn EVP_SealFinal +did not return a value before OpenSSL 0.9.7. diff --git a/src/lib/libcrypto/man/EVP_SignInit.3 b/src/lib/libcrypto/man/EVP_SignInit.3 new file mode 100644 index 0000000000..22f81148a2 --- /dev/null +++ b/src/lib/libcrypto/man/EVP_SignInit.3 @@ -0,0 +1,167 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_SIGNINIT 3 +.Os +.Sh NAME +.Nm EVP_SignInit , +.Nm EVP_SignUpdate , +.Nm EVP_SignFinal , +.Nm EVP_PKEY_size +.Nd EVP signing functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_SignInit_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *impl" +.Fc +.Ft int +.Fo EVP_SignUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "unsigned int cnt" +.Fc +.Ft int +.Fo EVP_SignFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sig" +.Fa "unsigned int *s" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft void +.Fo EVP_SignInit +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fc +.Ft int +.Fo EVP_PKEY_size +.Fa "EVP_PKEY *pkey" +.Fc +.Sh DESCRIPTION +The EVP signature routines are a high level interface to digital +signatures. +.Pp +.Fn EVP_SignInit_ex +sets up a signing context +.Fa ctx +to use the digest +.Fa type +from +.Vt ENGINE +.Fa impl . +.Fa ctx +must be initialized with +.Xr EVP_MD_CTX_init 3 +before calling this function. +.Pp +.Fn EVP_SignUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the signature context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +.Pp +.Fn EVP_SignFinal +signs the data in +.Fa ctx +using the private key +.Fa pkey +and places the signature in +.Fa sig . +.Fa sig +must be at least +.Fn EVP_PKEY_size pkey +bytes in size. +.Fa s +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 +.Fa s . +At most +.Fn EVP_PKEY_size pkey +bytes will be written. +.Pp +.Fn EVP_SignInit +initializes a signing context +.Fa ctx +to use the default implementation of digest +.Fa type . +.Pp +.Fn EVP_PKEY_size +returns the maximum size of a signature in bytes. +The actual signature returned by +.Fn EVP_SignFinal +may be smaller. +.Pp +The EVP 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. +.Pp +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 +.Xr EVP_DigestInit 3 . +.Pp +The call to +.Fn EVP_SignFinal +internally finalizes a copy of the digest context. +This means that calls to +.Fn EVP_SignUpdate +and +.Fn EVP_SignFinal +can be called later to digest and sign additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_cleanup 3 +or a memory leak will occur. +.Sh RETURN VALUES +.Fn EVP_SignInit_ex , +.Fn EVP_SignUpdate , +and +.Fn EVP_SignFinal +return 1 for success and 0 for failure. +.Pp +.Fn EVP_PKEY_size +returns the maximum size of a signature in bytes. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR 3 , +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_VerifyInit 3 +.Sh HISTORY +.Fn EVP_SignInit , +.Fn EVP_SignUpdate , +and +.Fn EVP_SignFinal +are available in all versions of SSLeay and OpenSSL. +.Pp +.Fn EVP_SignInit_ex +was added in OpenSSL 0.9.7. +.Sh BUGS +Older versions of this documentation wrongly stated that calls to +.Fn EVP_SignUpdate +could not be made after calling +.Fn EVP_SignFinal . +.Pp +Since the private key is passed in the call to +.Fn 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 +.Fn EVP_SignUpdate . +.Pp +It is not possible to change the signing parameters using these +function. +.Pp +The previous two bugs are fixed in the newer +.Xr EVP_SignDigest* 3 +function. diff --git a/src/lib/libcrypto/man/EVP_VerifyInit.3 b/src/lib/libcrypto/man/EVP_VerifyInit.3 new file mode 100644 index 0000000000..b1635d4cac --- /dev/null +++ b/src/lib/libcrypto/man/EVP_VerifyInit.3 @@ -0,0 +1,146 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP_VERIFYINIT 3 +.Os +.Sh NAME +.Nm EVP_VerifyInit , +.Nm EVP_VerifyUpdate , +.Nm EVP_VerifyFinal +.Nd EVP signature verification functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_VerifyInit_ex +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fa "ENGINE *impl" +.Fc +.Ft int +.Fo EVP_VerifyUpdate +.Fa "EVP_MD_CTX *ctx" +.Fa "const void *d" +.Fa "unsigned int cnt" +.Fc +.Ft int +.Fo EVP_VerifyFinal +.Fa "EVP_MD_CTX *ctx" +.Fa "unsigned char *sigbuf" +.Fa "unsigned int siglen" +.Fa "EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_VerifyInit +.Fa "EVP_MD_CTX *ctx" +.Fa "const EVP_MD *type" +.Fc +.Sh DESCRIPTION +The EVP signature verification routines are a high level interface to +digital signatures. +.Pp +.Fn EVP_VerifyInit_ex +sets up a verification context +.Fa ctx +to use the digest +.Fa type +from +.Vt ENGINE +.Fa impl . +.Fa ctx +must be initialized by calling +.Xr EVP_MD_CTX_init 3 +before calling this function. +.Pp +.Fn EVP_VerifyUpdate +hashes +.Fa cnt +bytes of data at +.Fa d +into the verification context +.Fa ctx . +This function can be called several times on the same +.Fa ctx +to include additional data. +.Pp +.Fn EVP_VerifyFinal +verifies the data in +.Fa ctx +using the public key +.Fa pkey +and against the +.Fa siglen +bytes at +.Fa sigbuf . +.Pp +.Fn EVP_VerifyInit +initializes a verification context +.Fa ctx +to use the default implementation of digest +.Fa type . +.Pp +The EVP 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. +.Pp +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 +.Xr EVP_DigestInit 3 . +.Pp +The call to +.Fn EVP_VerifyFinal +internally finalizes a copy of the digest context. +This means that calls to +.Fn EVP_VerifyUpdate +and +.Fn EVP_VerifyFinal +can be called later to digest and verify additional data. +.Pp +Since only a copy of the digest context is ever finalized, the context +must be cleaned up after use by calling +.Xr EVP_MD_CTX_cleanup 3 , +or a memory leak will occur. +.Sh RETURN VALUES +.Fn EVP_VerifyInit_ex +and +.Fn EVP_VerifyUpdate +return 1 for success and 0 for failure. +.Pp +.Fn EVP_VerifyFinal +returns 1 for a correct signature, 0 for failure, and -1 if some other +error occurred. +.Pp +The error codes can be obtained by +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR 3 , +.Xr evp 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_SignInit 3 +.Sh HISTORY +.Fn EVP_VerifyInit , +.Fn EVP_VerifyUpdate , +and +.Fn EVP_VerifyFinal +are available in all versions of SSLeay and OpenSSL. +.Pp +.Fn EVP_VerifyInit_ex +was added in OpenSSL 0.9.7. +.Sh BUGS +Older versions of this documentation wrongly stated that calls to +.Fn EVP_VerifyUpdate +could not be made after calling +.Fn EVP_VerifyFinal . +.Pp +Since the public key is passed in the call to +.Xr EVP_SignFinal 3 , +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 +.Xr EVP_SignUpdate 3 . +.Pp +It is not possible to change the signing parameters using these +functions. +.Pp +The previous two bugs are fixed in the newer functions of the +.Xr EVP_DigestVerifyInit 3 +family. diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 5d19e023ab..f4fd152ff7 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.37 2016/11/02 15:23:41 schwarze Exp $ +# $OpenBSD: Makefile,v 1.38 2016/11/03 09:35:34 schwarze Exp $ .include # for NOMAN @@ -92,14 +92,6 @@ MAN= \ ERR_remove_state.3 \ ERR_set_mark.3 \ EVP_AEAD_CTX_init.3 \ - UI_new.3 \ - bn_dump.3 \ - crypto.3 \ - d2i_PKCS8PrivateKey_bio.3 \ - des_read_pw.3 \ - lh_new.3 \ - -GENMAN= \ EVP_BytesToKey.3 \ EVP_DigestInit.3 \ EVP_DigestSignInit.3 \ @@ -123,6 +115,15 @@ GENMAN= \ EVP_SealInit.3 \ EVP_SignInit.3 \ EVP_VerifyInit.3 \ + UI_new.3 \ + bn_dump.3 \ + crypto.3 \ + d2i_PKCS8PrivateKey_bio.3 \ + des_read_pw.3 \ + evp.3 \ + lh_new.3 \ + +GENMAN= \ HMAC.3 \ MD5.3 \ OBJ_nid2obj.3 \ @@ -192,7 +193,6 @@ GENMAN= \ dsa.3 \ ec.3 \ engine.3 \ - evp.3 \ i2d_PKCS7_bio_stream.3 \ lh_stats.3 \ rsa.3 \ diff --git a/src/lib/libcrypto/man/evp.3 b/src/lib/libcrypto/man/evp.3 new file mode 100644 index 0000000000..7bf7dfec81 --- /dev/null +++ b/src/lib/libcrypto/man/evp.3 @@ -0,0 +1,151 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt EVP 3 +.Os +.Sh NAME +.Nm evp +.Nd high-level cryptographic functions +.Sh SYNOPSIS +.In openssl/evp.h +.Sh DESCRIPTION +The EVP library provides a high-level interface to cryptographic +functions. +.Pp +.Xr EVP_SealInit 3 +and +.Xr EVP_OpenInit 3 +provide public key encryption and decryption to implement digital +"envelopes". +.Pp +The +.Xr EVP_DigestSignInit 3 +and +.Xr EVP_DigestVerifyInit 3 +functions implement digital signatures and Message Authentication Codes +(MACs). +Also see the older +.Xr EVP_SignInit 3 +and +.Xr EVP_VerifyInit 3 +functions. +.Pp +Symmetric encryption is available with the +.Xr EVP_EncryptInit 3 +functions. +The +.Xr EVP_DigestInit 3 +functions provide message digests. +.Pp +Authenticated encryption with additional data (AEAD) is available with +the +.Xr EVP_AEAD_CTX_init 3 +functions. +.Pp +The +.Fn EVP_PKEY_* +functions provide a high level interface to asymmetric algorithms. +To create a new +.Vt EVP_PKEY , +see +.Xr EVP_PKEY_new 3 . +.Vt EVP_PKEY Ns s +can be associated with a private key of a particular algorithm +by using the functions described in the +.Xr EVP_PKEY_set1_RSA 3 +page, or new keys can be generated using +.Xr EVP_PKEY_keygen 3 . +.Vt EVP_PKEY Ns s +can be compared using +.Xr EVP_PKEY_cmp 3 +or printed using +.Xr EVP_PKEY_print_private 3 . +.Pp +The +.Fn EVP_PKEY_* +functions support the full range of asymmetric algorithm operations: +.Bl -bullet +.It +For key agreement, see +.Xr EVP_PKEY_derive 3 . +.It +For signing and verifying, see +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +and +.Xr EVP_PKEY_verify_recover 3 . +However, note that these functions do not perform a digest of the +data to be signed. +Therefore normally you would use the +.Xr EVP_DigestSignInit 3 +functions for this purpose. +.It +For encryption and decryption see +.Xr EVP_PKEY_encrypt 3 +and +.Xr EVP_PKEY_decrypt 3 , +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 +.Xr EVP_SealInit 3 +and +.Xr EVP_OpenInit 3 +functions. +.El +.Pp +The +.Xr EVP_BytesToKey 3 +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 typically not use this (preferring, for +example, PBKDF2 from PCKS#5). +.Pp +Algorithms are loaded with +.Xr OpenSSL_add_all_algorithms 3 . +.Pp +All the symmetric algorithms (ciphers), digests and asymmetric +algorithms (public key algorithms) can be replaced by +.Xr engine 3 +modules providing alternative implementations. +If +.Vt ENGINE +implementations of ciphers or digests are registered as defaults, +then the various EVP functions will automatically use those +implementations in preference to built in software implementations. +For more information, consult the +.Xr engine 3 +manual page. +.Pp +Although low level algorithm specific functions exist for many +algorithms, their use is discouraged. +They cannot be used with an +.Vt ENGINE , +and +.Vt ENGINE +versions of new algorithms cannot be accessed using the low level +functions. +Using them also makes code harder to adapt to new algorithms, some +options are not cleanly supported at the low level, and some +operations are more efficient using the high level interfaces. +.Sh SEE ALSO +.Xr engine 3 , +.Xr EVP_AEAD_CTX_init 3 , +.Xr EVP_BytesToKey 3 , +.Xr EVP_DigestInit 3 , +.Xr EVP_DigestSignInit 3 , +.Xr EVP_EncryptInit 3 , +.Xr EVP_OpenInit 3 , +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_keygen 3 , +.Xr EVP_PKEY_new 3 , +.Xr EVP_PKEY_print_private 3 , +.Xr EVP_PKEY_set1_RSA 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_verify 3 , +.Xr EVP_PKEY_verify_recover 3 , +.Xr EVP_SealInit 3 , +.Xr EVP_SignInit 3 , +.Xr EVP_VerifyInit 3 , +.Xr OpenSSL_add_all_algorithms 3 -- cgit v1.2.3-55-g6feb