diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2002-10-07 17:31:00 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2002-10-07 17:31:00 +0000 |
commit | d30e4c5b0bdcb8063ef25827af08f934a266cdab (patch) | |
tree | 42486ed459c6e556e0b1bf74d2733dfb1b6ddf77 | |
parent | 9de6bb8abc5296a79dbd85b0f86c533d5aab685b (diff) |
More docs.
-rw-r--r-- | doc/crypto/EVP_PKEY_new.pod | 47 | ||||
-rw-r--r-- | doc/crypto/EVP_PKEY_set1_RSA.pod | 80 | ||||
-rw-r--r-- | doc/crypto/PKCS7_sign.pod | 63 |
3 files changed, 190 insertions, 0 deletions
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 <openssl/evp.h> + + EVP_PKEY *EVP_PKEY_new(void); + void EVP_PKEY_free(EVP_PKEY *key); + + +=head1 DESCRIPTION + +The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> +structure which is used by OpenSSL to store private keys. + +EVP_PKEY_free() frees up the private key B<key>. + +=head1 NOTES + +The B<EVP_PKEY> 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<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> should be used. + +=head1 RETURN VALUES + +EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> +structure of B<NULL> if an error occurred. + +EVP_PKEY_free() does not return a value. + +=head1 SEE ALSO + +L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> + +=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 <openssl/evp.h> + + 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<pkey> to B<key>. + +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() +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. + +EVP_PKEY_type() returns the type of key corresponding to the value +B<type>. 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<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. + +=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<NULL> 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<EVP_PKEY_new(3)|EVP_PKEY_new(3)> + +=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<signcert> +is the certificate to sign with, B<pkey> is the corresponsding private key. +B<certs> 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<data>. + +B<flags> is an optional set of flags. + +=head1 NOTES + +Any of the following flags (ored together) can be passed in the B<flags> parameter. + +Many S/MIME clients expect the signed content to include valid MIME headers. If +the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are prepended +to the data. + +If B<PKCS7_NOCERTS> 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<signcert> +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<PKCS7_DETACHED> +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<PKCS7_BINARY> 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<PKCS7_NOATTR> is set then no authenticatedAttributes +will be used. If B<PKCS7_NOSMIMECAP> 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<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> + +=head1 HISTORY + +TBA + +=cut |