From d30e4c5b0bdcb8063ef25827af08f934a266cdab Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Mon, 7 Oct 2002 17:31:00 +0000 Subject: [PATCH] More docs. --- doc/crypto/EVP_PKEY_new.pod | 47 +++++++++++++++++++ doc/crypto/EVP_PKEY_set1_RSA.pod | 80 ++++++++++++++++++++++++++++++++ doc/crypto/PKCS7_sign.pod | 63 +++++++++++++++++++++++++ 3 files changed, 190 insertions(+) create mode 100644 doc/crypto/EVP_PKEY_new.pod create mode 100644 doc/crypto/EVP_PKEY_set1_RSA.pod create mode 100644 doc/crypto/PKCS7_sign.pod diff --git a/doc/crypto/EVP_PKEY_new.pod b/doc/crypto/EVP_PKEY_new.pod new file mode 100644 index 0000000000..10687e458d --- /dev/null +++ b/doc/crypto/EVP_PKEY_new.pod @@ -0,0 +1,47 @@ +=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 + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/EVP_PKEY_set1_RSA.pod b/doc/crypto/EVP_PKEY_set1_RSA.pod new file mode 100644 index 0000000000..2db692e271 --- /dev/null +++ b/doc/crypto/EVP_PKEY_set1_RSA.pod @@ -0,0 +1,80 @@ +=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 + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/PKCS7_sign.pod b/doc/crypto/PKCS7_sign.pod new file mode 100644 index 0000000000..95c4609d3c --- /dev/null +++ b/doc/crypto/PKCS7_sign.pod @@ -0,0 +1,63 @@ +=pod + +=head1 NAME + +PKCS7_sign - create a PKCS#7 signedData structure + +=head1 SYNOPSIS + +PKCS7 *PKCS7_sign(X509 *signcert, EVP_PKEY *pkey, STACK_OF(X509) *certs, BIO *data, int flags); + +=head1 DESCRIPTION + +PKCS7_sign() creates and returns a PKCS#7 signedData structure. B +is the certificate to sign with, B is the corresponsding private key. +B is an optional additional set of certificates to include in the +PKCS#7 structure (for example any intermediate CAs in the chain). + +The data to be signed is read from BIO B. + +B is an optional set of flags. + +=head1 NOTES + +Any of the following flags (ored together) can be passed in the B parameter. + +Many S/MIME clients expect the signed content to include valid MIME headers. If +the B flag is set MIME headers for type B are prepended +to the data. + +If B is set the signer's certificate will not be included in the +PKCS7 structure, the signer's certificate must still be supplied in the B +parameter though. This can reduce the size of the signature if the signers certificate +can be obtained by other means: for example a previously signed message. + +The data being signed is included in the PKCS7 structure, unless B +is set in which case it is omitted. This is used for PKCS7 detached signatures +which are used in S/MIME plaintext signed messages for example. + +Normally the supplied content is translated into MIME canonical format (as required +by the S/MIME specifications) if B is set no translation occurs. This +option should be used if the supplied data is in binary format otherwise the translation +will corrupt it. + +The signedData structure includes several PKCS#7 autenticatedAttributes including +the signing time, the PKCS#7 content type and the supported list of ciphers in +an SMIMECapabilities attribute. If B is set then no authenticatedAttributes +will be used. If B is set then just the SMIMECapabilities are +omitted. + +=head1 RETURN VALUES + +PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred. +The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +TBA + +=cut -- 2.25.1