diff options
Diffstat (limited to 'openssl/doc/crypto')
| -rw-r--r-- | openssl/doc/crypto/BIO_s_accept.pod | 4 | ||||
| -rw-r--r-- | openssl/doc/crypto/CMS_add1_signer.pod (renamed from openssl/doc/crypto/CMS_sign_add1_signer.pod) | 14 | ||||
| -rw-r--r-- | openssl/doc/crypto/EVP_DigestInit.pod | 30 | ||||
| -rw-r--r-- | openssl/doc/crypto/EVP_DigestVerifyInit.pod | 4 | ||||
| -rw-r--r-- | openssl/doc/crypto/EVP_EncryptInit.pod | 56 | ||||
| -rw-r--r-- | openssl/doc/crypto/EVP_PKEY_set1_RSA.pod | 8 | ||||
| -rw-r--r-- | openssl/doc/crypto/EVP_PKEY_sign.pod | 20 |
7 files changed, 70 insertions, 66 deletions
diff --git a/openssl/doc/crypto/BIO_s_accept.pod b/openssl/doc/crypto/BIO_s_accept.pod index 7b63e4621..b80b6ae48 100644 --- a/openssl/doc/crypto/BIO_s_accept.pod +++ b/openssl/doc/crypto/BIO_s_accept.pod @@ -59,8 +59,8 @@ the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> BIO_set_accept_port() uses the string B<name> to set the accept port. The port is represented as a string of the form "host:port", where "host" is the interface to use and "port" is the port. -Either or both values can be "*" which is interpreted as meaning -any interface or port respectively. "port" has the same syntax +The host can be can be "*" which is interpreted as meaning +any interface; "port" has the same syntax as the port specified in BIO_set_conn_port() for connect BIOs, that is it can be a numerical port string or a string to lookup using getservbyname() and a string table. diff --git a/openssl/doc/crypto/CMS_sign_add1_signer.pod b/openssl/doc/crypto/CMS_add1_signer.pod index bda3ca2ad..a055b8269 100644 --- a/openssl/doc/crypto/CMS_sign_add1_signer.pod +++ b/openssl/doc/crypto/CMS_add1_signer.pod @@ -2,20 +2,20 @@ =head1 NAME - CMS_sign_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. + CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. =head1 SYNOPSIS #include <openssl/cms.h> - CMS_SignerInfo *CMS_sign_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); + CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags); int CMS_SignerInfo_sign(CMS_SignerInfo *si); =head1 DESCRIPTION -CMS_sign_add1_signer() adds a signer with certificate B<signcert> and private +CMS_add1_signer() adds a signer with certificate B<signcert> and private key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData structure B<cms>. @@ -36,7 +36,7 @@ are both set. =head1 NOTES -The main purpose of CMS_sign_add1_signer() is to provide finer control +The main purpose of CMS_add1_signer() is to provide finer control over a CMS signed data structure where the simpler CMS_sign() function defaults are not appropriate. For example if multiple signers or non default digest algorithms are needed. New attributes can also be added using the returned @@ -80,13 +80,13 @@ bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is not loaded. -CMS_sign_add1_signer() returns an internal pointer to the CMS_SignerInfo +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added, this can be used to set additional attributes before it is finalized. =head1 RETURN VALUES -CMS_sign1_add_signers() returns an internal pointer to the CMS_SignerInfo +CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo structure just added or NULL if an error occurs. =head1 SEE ALSO @@ -96,6 +96,6 @@ L<CMS_final(3)|CMS_final(3)>, =head1 HISTORY -CMS_sign_add1_signer() was added to OpenSSL 0.9.8 +CMS_add1_signer() was added to OpenSSL 0.9.8 =cut diff --git a/openssl/doc/crypto/EVP_DigestInit.pod b/openssl/doc/crypto/EVP_DigestInit.pod index 310c65eb3..ac526bb6d 100644 --- a/openssl/doc/crypto/EVP_DigestInit.pod +++ b/openssl/doc/crypto/EVP_DigestInit.pod @@ -26,13 +26,13 @@ EVP digest routines int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); - int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); + int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); - int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); + int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); #define EVP_MAX_MD_SIZE 64 /* SHA512 */ @@ -136,10 +136,10 @@ reasons. EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(), EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2 -and RIPEMD160 digest algorithms respectively. +and RIPEMD160 digest algorithms respectively. EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest -algorithms but using DSS (DSA) for the signature algorithm. Note: there is +algorithms but using DSS (DSA) for the signature algorithm. Note: there is no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are however retained for compatibility. @@ -177,21 +177,21 @@ The B<EVP> interface to message digests should almost always be used in preference to the low level interfaces. This is because the code then becomes transparent to the digest used and much more flexible. -New applications should use the SHA2 digest algorithms such as SHA256. +New applications should use the SHA2 digest algorithms such as SHA256. The other digest algorithms are still in common use. For most applications the B<impl> parameter to EVP_DigestInit_ex() will be set to NULL to use the default digest implementation. -The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are +The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are obsolete but are retained to maintain compatibility with existing code. New -applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and +applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context instead of initializing and cleaning it up on each call and allow non default implementations of digests to be specified. In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use -memory leaks will occur. +memory leaks will occur. Stack allocation of EVP_MD_CTX structures is common, for example: @@ -245,15 +245,19 @@ digest name passed on the command line. EVP_MD_CTX_destroy(mdctx); printf("Digest is: "); - for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); + for(i = 0; i < md_len; i++) + printf("%02x", md_value[i]); printf("\n"); + + /* Call this once before exit. */ + EVP_cleanup(); + exit(0); } =head1 SEE ALSO -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> +L<dgst(1)|dgst(1)>, +L<evp(3)|evp(3)> =head1 HISTORY @@ -269,7 +273,7 @@ EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were changed to return truely const EVP_MD * in OpenSSL 0.9.7. The link between digests and signing algorithms was fixed in OpenSSL 1.0 and -later, so now EVP_sha1() can be used with RSA and DSA, there is no need to +later, so now EVP_sha1() can be used with RSA and DSA; there is no need to use EVP_dss1() any more. OpenSSL 1.0 and later does not include the MD2 digest algorithm in the diff --git a/openssl/doc/crypto/EVP_DigestVerifyInit.pod b/openssl/doc/crypto/EVP_DigestVerifyInit.pod index f22448897..cfeccd96e 100644 --- a/openssl/doc/crypto/EVP_DigestVerifyInit.pod +++ b/openssl/doc/crypto/EVP_DigestVerifyInit.pod @@ -38,7 +38,7 @@ or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm. Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only -indicates that the signature did not not verify successfully (that is tbs did +indicates that the signature did not verify successfully (that is tbs did not match the original data or the signature was of invalid form) it is not an indication of a more serious error. @@ -59,7 +59,7 @@ For some key types and parameters the random number generator must be seeded or the operation will fail. The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest -context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can +context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can be called later to digest and verify additional data. Since only a copy of the digest context is ever finalized the context must diff --git a/openssl/doc/crypto/EVP_EncryptInit.pod b/openssl/doc/crypto/EVP_EncryptInit.pod index d11e054e4..4e22edcd6 100644 --- a/openssl/doc/crypto/EVP_EncryptInit.pod +++ b/openssl/doc/crypto/EVP_EncryptInit.pod @@ -387,27 +387,7 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. =head1 EXAMPLES -Get the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds); - -Get the RC2 effective key length: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits); - -Set the number of rounds used in RC5: - - int nrounds; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL); - -Set the effective key length used in RC2: - - int key_bits; - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL); - -Encrypt a string using blowfish: +Encrypt a string using IDEA: int do_crypt(char *outfile) { @@ -421,8 +401,9 @@ Encrypt a string using blowfish: char intext[] = "Some Crypto Text"; EVP_CIPHER_CTX ctx; FILE *out; + EVP_CIPHER_CTX_init(&ctx); - EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv); + EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv); if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext))) { @@ -451,28 +432,34 @@ Encrypt a string using blowfish: } The ciphertext from the above example can be decrypted using the B<openssl> -utility with the command line: +utility with the command line (shown on two lines for clarity): - S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d> + openssl idea -d <filename + -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -General encryption, decryption function example using FILE I/O and RC2 with an -80 bit key: +General encryption and decryption function example using FILE I/O and AES128 +with a 128-bit key: int do_crypt(FILE *in, FILE *out, int do_encrypt) { /* Allow enough space in output buffer for additional block */ - inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; + unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; int inlen, outlen; + EVP_CIPHER_CTX ctx; /* Bogus key and IV: we'd normally set these from * another source. */ - unsigned char key[] = "0123456789"; - unsigned char iv[] = "12345678"; - /* Don't set key or IV because we will modify the parameters */ + unsigned char key[] = "0123456789abcdeF"; + unsigned char iv[] = "1234567887654321"; + + /* Don't set key or IV right away; we want to check lengths */ EVP_CIPHER_CTX_init(&ctx); - EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt); - EVP_CIPHER_CTX_set_key_length(&ctx, 10); - /* We finished modifying parameters so now we can set key and IV */ + EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, + do_encrypt); + OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16); + OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16); + + /* Now we can set key and IV */ EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt); for(;;) @@ -511,4 +498,7 @@ EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in OpenSSL 0.9.7. +IDEA appeared in OpenSSL 0.9.7 but was often disabled due to +patent concerns; the last patents expired in 2012. + =cut diff --git a/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod b/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod index 2db692e27..6f1017561 100644 --- a/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod +++ b/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod @@ -37,7 +37,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or B<NULL> if the key is not of the correct type. -EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() +EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key> however these use the supplied B<key> internally and so B<key> will be freed when the parent B<pkey> is freed. @@ -54,8 +54,8 @@ In accordance with the OpenSSL naming convention the key obtained from or assigned to the B<pkey> using the B<1> functions must be freed as well as B<pkey>. -EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() -EVP_PKEY_assign_EC_KEY() are implemented as macros. +EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() +and EVP_PKEY_assign_EC_KEY() are implemented as macros. =head1 RETURN VALUES @@ -66,7 +66,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if an error occurred. -EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() +EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure. =head1 SEE ALSO diff --git a/openssl/doc/crypto/EVP_PKEY_sign.pod b/openssl/doc/crypto/EVP_PKEY_sign.pod index a044f2c13..21974b4b1 100644 --- a/openssl/doc/crypto/EVP_PKEY_sign.pod +++ b/openssl/doc/crypto/EVP_PKEY_sign.pod @@ -28,9 +28,14 @@ B<sig> and the amount of data written to B<siglen>. =head1 NOTES +EVP_PKEY_sign() does not hash the data to be signed, and therefore is +normally used to sign digests. For signing arbitrary messages, see the +L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)> and +L<EVP_SignInit(3)|EVP_SignInit(3)> signing interfaces instead. + After the call to EVP_PKEY_sign_init() algorithm specific control operations can be performed to set any appropriate parameters for the -operation. +operation (see L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>). The function EVP_PKEY_sign() can be called more than once on the same context if several operations are performed using the same parameters. @@ -49,13 +54,17 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest: #include <openssl/rsa.h> EVP_PKEY_CTX *ctx; + /* md is a SHA-256 digest in this example. */ unsigned char *md, *sig; - size_t mdlen, siglen; + size_t mdlen = 32, siglen; EVP_PKEY *signing_key; - /* NB: assumes signing_key, md and mdlen are already set up - * and that signing_key is an RSA private key + + /* + * NB: assumes signing_key and md are set up before the next + * step. signing_key must be an RSA private key and md must + * point to the SHA-256 digest to be signed. */ - ctx = EVP_PKEY_CTX_new(signing_key); + ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); if (!ctx) /* Error occurred */ if (EVP_PKEY_sign_init(ctx) <= 0) @@ -83,6 +92,7 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest: =head1 SEE ALSO L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>, L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, |