diff options
27 files changed, 2231 insertions, 1371 deletions
diff --git a/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod b/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod deleted file mode 100644 index 6d87079a843..00000000000 --- a/lib/libcrypto/doc/PEM_read_bio_PrivateKey.pod +++ /dev/null @@ -1,498 +0,0 @@ -=pod - -=head1 NAME - -PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, -PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, -PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, -PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, -PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, -PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, -PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, -PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, -PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, -PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, -PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, -PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, -PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, -PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, -PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, -PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, -PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, -PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, -PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, -PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, -PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, -PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, -PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines - -=head1 SYNOPSIS - - #include <openssl/pem.h> - - EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - - EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); - int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); - - RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - - RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - - RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); - - int PEM_write_RSAPublicKey(FILE *fp, RSA *x); - - RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - - RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); - - int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); - - DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, - pem_password_cb *cb, void *u); - - DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - - DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, - pem_password_cb *cb, void *u); - - DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); - - int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); - - DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); - - DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_DSAparams(BIO *bp, DSA *x); - - int PEM_write_DSAparams(FILE *fp, DSA *x); - - DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); - - DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_DHparams(BIO *bp, DH *x); - - int PEM_write_DHparams(FILE *fp, DH *x); - - X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); - - X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_X509(BIO *bp, X509 *x); - - int PEM_write_X509(FILE *fp, X509 *x); - - X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); - - X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); - - int PEM_write_X509_AUX(FILE *fp, X509 *x); - - X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, - pem_password_cb *cb, void *u); - - X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); - - int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); - - int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); - - int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); - - X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, - pem_password_cb *cb, void *u); - X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, - pem_password_cb *cb, void *u); - int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); - int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); - - PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); - - PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); - - int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); - - int PEM_write_PKCS7(FILE *fp, PKCS7 *x); - - NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); - - int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); - -=head1 DESCRIPTION - -The PEM functions read or write structures in PEM format. In -this sense PEM format is simply base64 encoded data surrounded -by header lines. - -For more details about the meaning of arguments see the -B<PEM FUNCTION ARGUMENTS> section. - -Each operation has four functions associated with it. For -clarity the term "B<foobar> functions" will be used to collectively -refer to the PEM_read_bio_foobar(), PEM_read_foobar(), -PEM_write_bio_foobar() and PEM_write_foobar() functions. - -The B<PrivateKey> functions read or write a private key in -PEM format using an EVP_PKEY structure. The write routines use -"traditional" private key format and can handle both RSA and DSA -private keys. The read functions can additionally transparently -handle PKCS#8 format encrypted and unencrypted keys too. - -PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() -write a private key in an EVP_PKEY structure in PKCS#8 -EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption -algorithms. The B<cipher> argument specifies the encryption algorithm to -use: unlike all other PEM routines the encryption is applied at the -PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no -encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. - -PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() -also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however -it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm -to use is specified in the B<nid> parameter and should be the NID of the -corresponding OBJECT IDENTIFIER (see NOTES section). - -The B<PUBKEY> functions process a public key using an EVP_PKEY -structure. The public key is encoded as a SubjectPublicKeyInfo -structure. - -The B<RSAPrivateKey> functions process an RSA private key using an -RSA structure. It handles the same formats as the B<PrivateKey> -functions but an error occurs if the private key is not RSA. - -The B<RSAPublicKey> functions process an RSA public key using an -RSA structure. The public key is encoded using a PKCS#1 RSAPublicKey -structure. - -The B<RSA_PUBKEY> functions also process an RSA public key using -an RSA structure. However the public key is encoded using a -SubjectPublicKeyInfo structure and an error occurs if the public -key is not RSA. - -The B<DSAPrivateKey> functions process a DSA private key using a -DSA structure. It handles the same formats as the B<PrivateKey> -functions but an error occurs if the private key is not DSA. - -The B<DSA_PUBKEY> functions process a DSA public key using -a DSA structure. The public key is encoded using a -SubjectPublicKeyInfo structure and an error occurs if the public -key is not DSA. - -The B<DSAparams> functions process DSA parameters using a DSA -structure. The parameters are encoded using a foobar structure. - -The B<DHparams> functions process DH parameters using a DH -structure. The parameters are encoded using a PKCS#3 DHparameter -structure. - -The B<X509> functions process an X509 certificate using an X509 -structure. They will also process a trusted X509 certificate but -any trust settings are discarded. - -The B<X509_AUX> functions process a trusted X509 certificate using -an X509 structure. - -The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10 -certificate request using an X509_REQ structure. The B<X509_REQ> -write functions use B<CERTIFICATE REQUEST> in the header whereas -the B<X509_REQ_NEW> functions use B<NEW CERTIFICATE REQUEST> -(as required by some CAs). The B<X509_REQ> read functions will -handle either form so there are no B<X509_REQ_NEW> read functions. - -The B<X509_CRL> functions process an X509 CRL using an X509_CRL -structure. - -The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7 -structure. - -The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate -Sequence using a NETSCAPE_CERT_SEQUENCE structure. - -=head1 PEM FUNCTION ARGUMENTS - -The PEM functions have many common arguments. - -The B<bp> BIO parameter (if present) specifies the BIO to read from -or write to. - -The B<fp> FILE parameter (if present) specifies the FILE pointer to -read from or write to. - -The PEM read functions all take an argument B<TYPE **x> and return -a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function -uses. If B<x> is NULL then the parameter is ignored. If B<x> is not -NULL but B<*x> is NULL then the structure returned will be written -to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made -to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections). -Irrespective of the value of B<x> a pointer to the structure is always -returned (or NULL if an error occurred). - -The PEM functions which write private keys take an B<enc> parameter -which specifies the encryption algorithm to use, encryption is done -at the PEM level. If this parameter is set to NULL then the private -key is written in unencrypted form. - -The B<cb> argument is the callback to use when querying for the pass -phrase used for encrypted PEM structures (normally only private keys). - -For the PEM write routines if the B<kstr> parameter is not NULL then -B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is -ignored. - -If the B<cb> parameters is set to NULL and the B<u> parameter is not -NULL then the B<u> parameter is interpreted as a null terminated string -to use as the passphrase. If both B<cb> and B<u> are NULL then the -default callback routine is used which will typically prompt for the -passphrase on the current terminal with echoing turned off. - -The default passphrase callback is sometimes inappropriate (for example -in a GUI application) so an alternative can be supplied. The callback -routine has the following form: - - int cb(char *buf, int size, int rwflag, void *u); - -B<buf> is the buffer to write the passphrase to. B<size> is the maximum -length of the passphrase (i.e. the size of buf). B<rwflag> is a flag -which is set to 0 when reading and 1 when writing. A typical routine -will ask the user to verify the passphrase (for example by prompting -for it twice) if B<rwflag> is 1. The B<u> parameter has the same -value as the B<u> parameter passed to the PEM routine. It allows -arbitrary data to be passed to the callback by the application -(for example a window handle in a GUI application). The callback -B<must> return the number of characters in the passphrase or 0 if -an error occurred. - -=head1 EXAMPLES - -Although the PEM routines take several arguments in almost all applications -most of them are set to 0 or NULL. - -Read a certificate in PEM format from a BIO: - - X509 *x; - x = PEM_read_bio_X509(bp, NULL, 0, NULL); - if (x == NULL) { - /* Error */ - } - -Alternative method: - - X509 *x = NULL; - if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { - /* Error */ - } - -Write a certificate to a BIO: - - if (!PEM_write_bio_X509(bp, x)) { - /* Error */ - } - -Write an unencrypted private key to a FILE pointer: - - if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) { - /* Error */ - } - -Write a private key (using traditional format) to a BIO using -triple DES encryption, the pass phrase is prompted for: - - if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), - NULL, 0, 0, NULL)) { - /* Error */ - } - -Write a private key (using PKCS#8 format) to a BIO using triple -DES encryption, using the pass phrase "hello": - - if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), - NULL, 0, 0, "hello")) { - /* Error */ - } - -Read a private key from a BIO using the pass phrase "hello": - - key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); - if (key == NULL) { - /* Error */ - } - -Read a private key from a BIO using a pass phrase callback: - - key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); - if (key == NULL) { - /* Error */ - } - -Skeleton pass phrase callback: - - int - pass_cb(char *buf, int size, int rwflag, void *u) - { - int len; - char *tmp; - - /* We'd probably do something else if 'rwflag' is 1 */ - printf("Enter pass phrase for \"%s\"\n", u); - - /* get pass phrase, length 'len' into 'tmp' */ - tmp = "hello"; - len = strlen(tmp); - - if (len == 0) - return 0; - /* if too long, truncate */ - if (len > size) - len = size; - memcpy(buf, tmp, len); - return len; - } - -=head1 NOTES - -The old B<PrivateKey> write routines are retained for compatibility. -New applications should write private keys using the -PEM_write_bio_PKCS8PrivateKey() or PEM_write_PKCS8PrivateKey() routines -because they are more secure (they use an iteration count of 2048 whereas -the traditional routines use a count of 1) unless compatibility with older -versions of OpenSSL is important. - -The B<PrivateKey> read routines can be used in all applications because -they handle all formats transparently. - -A frequent cause of problems is attempting to use the PEM routines like -this: - - X509 *x; - PEM_read_bio_X509(bp, &x, 0, NULL); - -this is a bug because an attempt will be made to reuse the data at B<x> -which is an uninitialised pointer. - -=head1 PEM ENCRYPTION FORMAT - -This old B<PrivateKey> routines use a non standard technique for encryption. - -The private key (or other data) takes the following form: - - -----BEGIN RSA PRIVATE KEY----- - Proc-Type: 4,ENCRYPTED - DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 - - ...base64 encoded data... - -----END RSA PRIVATE KEY----- - -The line beginning DEK-Info contains two comma separated pieces of information: -the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 -byte B<salt> encoded as a set of hexadecimal digits. - -After this is the base64 encoded encrypted data. - -The encryption key is determined using EVP_bytestokey(), using B<salt> and an -iteration count of 1. The IV used is the value of B<salt> and *not* the IV -returned by EVP_bytestokey(). - -=head1 BUGS - -The PEM read routines in some versions of OpenSSL will not correctly reuse -an existing structure. Therefore the following: - - PEM_read_bio_X509(bp, &x, 0, NULL); - -where B<x> already contains a valid certificate, may not work, whereas: - - X509_free(x); - x = PEM_read_bio_X509(bp, NULL, 0, NULL); - -is guaranteed to work. - -=head1 RETURN CODES - -The read routines return either a pointer to the structure read or NULL -if an error occurred. - -The write routines return 1 for success or 0 for failure. - -=cut diff --git a/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod b/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod deleted file mode 100644 index 16fc9b68458..00000000000 --- a/lib/libcrypto/doc/PEM_write_bio_PKCS7_stream.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format. - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - #include <openssl/pem.h> - - int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); - -=head1 DESCRIPTION - -PEM_write_bio_PKCS7_stream() outputs a PKCS7 structure in PEM format. - -It is otherwise identical to the function SMIME_write_PKCS7(). - -=head1 NOTES - -This function is effectively a version of the PEM_write_bio_PKCS7() supporting -streaming. - -=head1 RETURN VALUES - -PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, -L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, -L<i2d_PKCS7_bio_stream(3)|i2d_PKCS7_bio_stream(3)> - -=head1 HISTORY - -PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0 - -=cut diff --git a/lib/libcrypto/doc/PKCS12_create.pod b/lib/libcrypto/doc/PKCS12_create.pod deleted file mode 100644 index 3b27c11a104..00000000000 --- a/lib/libcrypto/doc/PKCS12_create.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -PKCS12_create - create a PKCS#12 structure - -=head1 SYNOPSIS - - #include <openssl/pkcs12.h> - - PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, - X509 *cert, STACK_OF(X509) *ca, int nid_key, int nid_cert, - int iter, int mac_iter, int keytype); - -=head1 DESCRIPTION - -PKCS12_create() creates a PKCS#12 structure. - -B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for -the supplied certificate and key. B<pkey> is the private key to include in -the structure and B<cert> its corresponding certificates. B<ca> is an optional -set of certificates to also include in the structure. -Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or -certificate is required. - -B<nid_key> and B<nid_cert> are the encryption algorithms that should be used -for the key and certificate respectively. If either B<nid_key> or B<nid_cert> -is set to -1, no encryption will be used. - -B<iter> is the encryption algorithm iteration count to use and B<mac_iter> is -the MAC iteration count to use. If B<mac_iter> is set to -1, the MAC will be -omitted entirely. - -B<keytype> is the type of key. - -=head1 NOTES - -The parameters B<nid_key>, B<nid_cert>, B<iter>, B<mac_iter> and B<keytype> -can all be set to zero and sensible defaults will be used. - -These defaults are: 40 bit RC2 encryption for certificates, triple DES -encryption for private keys, a key iteration count of PKCS12_DEFAULT_ITER -(currently 2048) and a MAC iteration count of 1. - -The default MAC iteration count is 1 in order to retain compatibility with -old software which did not interpret MAC iteration counts. If such compatibility -is not required then B<mac_iter> should be set to PKCS12_DEFAULT_ITER. - -B<keytype> adds a flag to the store private key. This is a non standard -extension that is only currently interpreted by MSIE. If set to zero the flag -is omitted, if set to B<KEY_SIG> the key can be used for signing only, if set -to B<KEY_EX> it can be used for signing and encryption. This option was useful -for old export grade software which could use signing only keys of arbitrary -size but had restrictions on the permissible sizes of keys which could be used -for encryption. - -If a certificate contains an B<alias> or B<keyid> then this will be -used for the corresponding B<friendlyName> or B<localKeyID> in the -PKCS12 structure. - -=head1 SEE ALSO - -L<d2i_PKCS12(3)|d2i_PKCS12(3)> - -=head1 HISTORY - -PKCS12_create was added in OpenSSL 0.9.3. - -Before OpenSSL 0.9.8, neither B<pkey> nor B<cert> were allowed to be B<NULL>, -and a value of B<-1> was not allowed for B<nid_key>, B<nid_cert> and -B<mac_iter>. - -=cut diff --git a/lib/libcrypto/doc/PKCS12_parse.pod b/lib/libcrypto/doc/PKCS12_parse.pod deleted file mode 100644 index 51344f883a9..00000000000 --- a/lib/libcrypto/doc/PKCS12_parse.pod +++ /dev/null @@ -1,50 +0,0 @@ -=pod - -=head1 NAME - -PKCS12_parse - parse a PKCS#12 structure - -=head1 SYNOPSIS - - #include <openssl/pkcs12.h> - -int PKCS12_parse(PKCS12 *p12, const char *pass, EVP_PKEY **pkey, X509 **cert, STACK_OF(X509) **ca); - -=head1 DESCRIPTION - -PKCS12_parse() parses a PKCS12 structure. - -B<p12> is the B<PKCS12> structure to parse. B<pass> is the passphrase to use. -If successful the private key will be written to B<*pkey>, the corresponding -certificate to B<*cert> and any additional certificates to B<*ca>. - -=head1 NOTES - -The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> -in which case additional certificates will be discarded. B<*ca> can also -be a valid STACK in which case additional certificates are appended to -B<*ca>. If B<*ca> is B<NULL> a new STACK will be allocated. - -The B<friendlyName> and B<localKeyID> attributes (if present) on each certificate -will be stored in the B<alias> and B<keyid> attributes of the B<X509> structure. - -=head1 BUGS - -Only a single private key and corresponding certificate is returned by this function. -More complex PKCS#12 files with multiple private keys will only return the first -match. - -Only B<friendlyName> and B<localKeyID> attributes are currently stored in certificates. -Other attributes are discarded. - -Attributes currently cannot be store in the private key B<EVP_PKEY> structure. - -=head1 SEE ALSO - -L<d2i_PKCS12(3)|d2i_PKCS12(3)> - -=head1 HISTORY - -PKCS12_parse was added in OpenSSL 0.9.3 - -=cut diff --git a/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod b/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod deleted file mode 100644 index 0c164a0ed6b..00000000000 --- a/lib/libcrypto/doc/PKCS5_PBKDF2_HMAC.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - int PKCS5_PBKDF2_HMAC(const char *pass, int passlen, - const unsigned char *salt, int saltlen, int iter, - const EVP_MD *digest, - int keylen, unsigned char *out); - -int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen, - const unsigned char *salt, int saltlen, int iter, - int keylen, unsigned char *out); - -=head1 DESCRIPTION - -PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count -as specified in RFC 2898. - -B<pass> is the password used in the derivation of length B<passlen>. B<pass> -is an optional parameter and can be NULL. If B<passlen> is -1, then the -function will calculate the length of B<pass> using strlen(). - -B<salt> is the salt used in the derivation of length B<saltlen>. If the -B<salt> is NULL, then B<saltlen> must be 0. The function will not -attempt to calculate the length of the B<salt> because it is not assumed to -be NULL terminated. - -B<iter> is the iteration count and its value should be greater than or -equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any -B<iter> less than 1 is treated as a single iteration. - -B<digest> is the message digest function used in the derivation. Values include -any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls -PKCS5_PBKDF2_HMAC() with EVP_sha1(). - -The derived key will be written to B<out>. The size of the B<out> buffer -is specified via B<keylen>. - -=head1 NOTES - -A typical application of this function is to derive keying material for an -encryption algorithm from a password in the B<pass>, a salt in B<salt>, -and an iteration count. - -Increasing the B<iter> 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. - -=head1 RETURN VALUES - -PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error. - -=head1 SEE ALSO - -L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> - -=cut diff --git a/lib/libcrypto/doc/PKCS7_decrypt.pod b/lib/libcrypto/doc/PKCS7_decrypt.pod deleted file mode 100644 index 78919998ce7..00000000000 --- a/lib/libcrypto/doc/PKCS7_decrypt.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int PKCS7_decrypt(PKCS7 *p7, EVP_PKEY *pkey, X509 *cert, BIO *data, int flags); - -=head1 DESCRIPTION - -PKCS7_decrypt() extracts and decrypts the content from a PKCS#7 envelopedData -structure. B<pkey> is the private key of the recipient, B<cert> is the -recipients certificate, B<data> is a BIO to write the content to and -B<flags> is an optional set of flags. - -=head1 NOTES - -OpenSSL_add_all_algorithms() (or equivalent) should be called before using this -function or errors about unknown algorithms will occur. - -Although the recipients certificate is not needed to decrypt the data it is -needed to locate the appropriate (of possible several) recipients in the PKCS#7 -structure. - -The following flags can be passed in the B<flags> parameter. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -returned. - -=head1 RETURN VALUES - -PKCS7_decrypt() returns either 1 for success or 0 for failure. -The error can be obtained from ERR_get_error(3) - -=head1 BUGS - -PKCS7_decrypt() must be passed the correct recipient key and certificate. It -would be better if it could look up the correct key and certificate from a -database. - -The lack of single pass processing and need to hold all data in memory as -mentioned in PKCS7_sign() also applies to PKCS7_verify(). - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> - -=head1 HISTORY - -PKCS7_decrypt() was added to OpenSSL 0.9.5 - -=cut diff --git a/lib/libcrypto/doc/PKCS7_encrypt.pod b/lib/libcrypto/doc/PKCS7_encrypt.pod deleted file mode 100644 index 8bc77407b9e..00000000000 --- a/lib/libcrypto/doc/PKCS7_encrypt.pod +++ /dev/null @@ -1,73 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_encrypt - create a PKCS#7 envelopedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - PKCS7 *PKCS7_encrypt(STACK_OF(X509) *certs, BIO *in, const EVP_CIPHER *cipher, int flags); - -=head1 DESCRIPTION - -PKCS7_encrypt() creates and returns a PKCS#7 envelopedData structure. B<certs> -is a list of recipient certificates. B<in> is the content to be encrypted. -B<cipher> is the symmetric cipher to use. B<flags> is an optional set of flags. - -=head1 NOTES - -Only RSA keys are supported in PKCS#7 and envelopedData so the recipient -certificates supplied to this function must all contain RSA public keys, though -they do not have to be signed using the RSA algorithm. - -The algorithm passed in the B<cipher> parameter must support ASN1 encoding of -its parameters. - -Many browsers implement a "sign and encrypt" option which is simply an S/MIME -envelopedData containing an S/MIME signed message. This can be readily produced -by storing the S/MIME signed message in a memory BIO and passing it to -PKCS7_encrypt(). - -The following flags can be passed in the B<flags> parameter. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are -prepended to the data. - -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. If B<PKCS7_BINARY> is set then -B<PKCS7_TEXT> is ignored. - -If the B<PKCS7_STREAM> flag is set a partial B<PKCS7> structure is output -suitable for streaming I/O: no data is read from the BIO B<in>. - -=head1 NOTES - -If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> -complete and outputting its contents via a function that does not -properly finalize the B<PKCS7> structure will give unpredictable -results. - -Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), -PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_PKCS7(). - -=head1 RETURN VALUES - -PKCS7_encrypt() returns either a 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_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -PKCS7_decrypt() was added to OpenSSL 0.9.5 -The B<PKCS7_STREAM> flag was first supported in OpenSSL 1.0.0. - -=cut diff --git a/lib/libcrypto/doc/PKCS7_sign.pod b/lib/libcrypto/doc/PKCS7_sign.pod deleted file mode 100644 index 64a3036c0a6..00000000000 --- a/lib/libcrypto/doc/PKCS7_sign.pod +++ /dev/null @@ -1,116 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_sign - create a PKCS#7 signedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - 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 corresponding 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 authenticatedAttributes -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. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of -these algorithms is disabled then it will not be included. - -If the flags B<PKCS7_STREAM> is set then the returned B<PKCS7> structure is -just initialized ready to perform the signing operation. The signing is however -B<not> performed and the data to be signed is not read from the B<data> -parameter. Signing is deferred until after the data has been written. In this -way data can be signed in a single pass. - -If the B<PKCS7_PARTIAL> flag is set a partial B<PKCS7> structure is output to -which additional signers and capabilities can be added before finalization. - - -=head1 NOTES - -If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> -complete and outputting its contents via a function that does not properly -finalize the B<PKCS7> structure will give unpredictable results. - -Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), -PEM_write_bio_PKCS7_stream() finalize the structure. Alternatively finalization -can be performed by obtaining the streaming ASN1 B<BIO> directly using -BIO_new_PKCS7(). - -If a signer is specified it will use the default digest for the signing -algorithm. This is B<SHA1> for both RSA and DSA keys. - -In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be -B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added -using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> must also be -called to finalize the structure if streaming is not enabled. Alternative -signing digests can also be specified using this method. - -In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only -PKCS#7 structure is output. - -In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must -B<NOT> be NULL. - -=head1 BUGS - -Some advanced attributes such as counter signatures are not supported. - -=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 - -PKCS7_sign() was added to OpenSSL 0.9.5 - -The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0 - -The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0 - -=cut diff --git a/lib/libcrypto/doc/PKCS7_sign_add_signer.pod b/lib/libcrypto/doc/PKCS7_sign_add_signer.pod deleted file mode 100644 index 280455d476c..00000000000 --- a/lib/libcrypto/doc/PKCS7_sign_add_signer.pod +++ /dev/null @@ -1,87 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_sign_add_signer - add a signer PKCS7 signed data structure. - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - PKCS7_SIGNER_INFO *PKCS7_sign_add_signer(PKCS7 *p7, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, int flags); - - -=head1 DESCRIPTION - -PKCS7_sign_add_signer() adds a signer with certificate B<signcert> and private -key B<pkey> using message digest B<md> to a PKCS7 signed data structure -B<p7>. - -The PKCS7 structure should be obtained from an initial call to PKCS7_sign() -with the flag B<PKCS7_PARTIAL> set or in the case or re-signing a valid PKCS7 -signed data structure. - -If the B<md> parameter is B<NULL> then the default digest for the public -key algorithm will be used. - -Unless the B<PKCS7_REUSE_DIGEST> flag is set the returned PKCS7 structure -is not complete and must be finalized either by streaming (if applicable) or -a call to PKCS7_final(). - - -=head1 NOTES - -The main purpose of this function is to provide finer control over a PKCS#7 -signed data structure where the simpler PKCS7_sign() function defaults are -not appropriate. For example if multiple signers or non default digest -algorithms are needed. - -Any of the following flags (ored together) can be passed in the B<flags> -parameter. - -If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content -digest value from the PKCS7 structure: to add a signer to an existing structure. -An error occurs if a matching digest value cannot be found to copy. The -returned PKCS7 structure will be valid and finalized when this flag is set. - -If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the -B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes -can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is -needed to finalize it. - -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 signedData structure includes several PKCS#7 authenticatedAttributes -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. - -If present the SMIMECapabilities attribute indicates support for the following -algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2. If any of -these algorithms is disabled then it will not be included. - - -PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO -structure just added, this can be used to set additional attributes -before it is finalized. - -=head1 RETURN VALUES - -PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO -structure just added or NULL if an error occurs. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_final(3)|PKCS7_final(3)>, - -=head1 HISTORY - -PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0 - -=cut diff --git a/lib/libcrypto/doc/PKCS7_verify.pod b/lib/libcrypto/doc/PKCS7_verify.pod deleted file mode 100644 index 059fbff8e9c..00000000000 --- a/lib/libcrypto/doc/PKCS7_verify.pod +++ /dev/null @@ -1,118 +0,0 @@ -=pod - -=head1 NAME - -PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags); - - STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags); - -=head1 DESCRIPTION - -PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7 -structure to verify. B<certs> is a set of certificates in which to search for -the signer's certificate. B<store> is a trusted certificate store (used for -chain verification). B<indata> is the signed data if the content is not -present in B<p7> (that is it is detached). The content is written to B<out> -if it is not NULL. - -B<flags> is an optional set of flags, which can be used to modify the verify -operation. - -PKCS7_get0_signers() retrieves the signer's certificates from B<p7>, it does -B<not> check their validity or whether any signatures are valid. The B<certs> -and B<flags> parameters have the same meanings as in PKCS7_verify(). - -=head1 VERIFY PROCESS - -Normally the verify process proceeds as follows. - -Initially some sanity checks are performed on B<p7>. The type of B<p7> must -be signedData. There must be at least one signature on the data and if -the content is detached B<indata> cannot be B<NULL>. - -An attempt is made to locate all the signer's certificates, first looking in -the B<certs> parameter (if it is not B<NULL>) and then looking in any -certificates contained in the B<p7> structure itself. If any signer's -certificates cannot be located the operation fails. - -Each signer's certificate is chain verified using the B<smimesign> purpose and -the supplied trusted certificate store. Any internal certificates in the message -are used as untrusted CAs. If any chain verify fails an error code is returned. - -Finally the signed content is read (and written to B<out> is it is not NULL) and -the signature's checked. - -If all signature's verify correctly then the function is successful. - -Any of the following flags (ored together) can be passed in the B<flags> -parameter to change the default verify behaviour. Only the flag -B<PKCS7_NOINTERN> is meaningful to PKCS7_get0_signers(). - -If B<PKCS7_NOINTERN> is set the certificates in the message itself are not -searched when locating the signer's certificate. This means that all the signers -certificates must be in the B<certs> parameter. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> are deleted -from the content. If the content is not of type B<text/plain> then an error is -returned. - -If B<PKCS7_NOVERIFY> is set the signer's certificates are not chain verified. - -If B<PKCS7_NOCHAIN> is set then the certificates contained in the message are -not used as untrusted CAs. This means that the whole verify chain (apart from -the signer's certificate) must be contained in the trusted store. - -If B<PKCS7_NOSIGS> is set then the signatures on the data are not checked. - -=head1 NOTES - -One application of B<PKCS7_NOINTERN> is to only accept messages signed by -a small number of certificates. The acceptable certificates would be passed -in the B<certs> parameter. In this case if the signer is not one of the -certificates supplied in B<certs> then the verify will fail because the -signer cannot be found. - -Care should be taken when modifying the default verify behaviour, for example -setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification -and any signed message will be considered valid. This combination is however -useful if one merely wishes to write the content to B<out> and its validity -is not considered important. - -Chain verification should arguably be performed using the signing time rather -than the current time. However since the signing time is supplied by the -signer it cannot be trusted without additional evidence (such as a trusted -timestamp). - -=head1 RETURN VALUES - -PKCS7_verify() returns 1 for a successful verification and zero or a negative -value if an error occurs. - -PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred. - -The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 BUGS - -The trusted certificate store is not searched for the signers certificate, -this is primarily due to the inadequacies of the current B<X509_STORE> -functionality. - -The lack of single pass processing and need to hold all data in memory as -mentioned in PKCS7_sign() also applies to PKCS7_verify(). - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)> - -=head1 HISTORY - -PKCS7_verify() was added to OpenSSL 0.9.5 - -=cut diff --git a/lib/libcrypto/doc/SMIME_read_PKCS7.pod b/lib/libcrypto/doc/SMIME_read_PKCS7.pod deleted file mode 100644 index ffafa378877..00000000000 --- a/lib/libcrypto/doc/SMIME_read_PKCS7.pod +++ /dev/null @@ -1,71 +0,0 @@ -=pod - -=head1 NAME - -SMIME_read_PKCS7 - parse S/MIME message. - -=head1 SYNOPSIS - -PKCS7 *SMIME_read_PKCS7(BIO *in, BIO **bcont); - -=head1 DESCRIPTION - -SMIME_read_PKCS7() parses a message in S/MIME format. - -B<in> is a BIO to read the message from. - -If cleartext signing is used then the content is saved in -a memory bio which is written to B<*bcont>, otherwise -B<*bcont> is set to B<NULL>. - -The parsed PKCS#7 structure is returned or B<NULL> if an -error occurred. - -=head1 NOTES - -If B<*bcont> is not B<NULL> then the message is clear text -signed. B<*bcont> can then be passed to PKCS7_verify() with -the B<PKCS7_DETACHED> flag set. - -Otherwise the type of the returned structure can be determined -using PKCS7_type(). - -To support future functionality if B<bcont> is not B<NULL> -B<*bcont> should be initialized to B<NULL>. For example: - - BIO *cont = NULL; - PKCS7 *p7; - - p7 = SMIME_read_PKCS7(in, &cont); - -=head1 BUGS - -The MIME parser used by SMIME_read_PKCS7() is somewhat primitive. -While it will handle most S/MIME messages more complex compound -formats may not work. - -The parser assumes that the PKCS7 structure is always base64 -encoded and will not handle the case where it is in binary format -or uses quoted printable format. - -The use of a memory BIO to hold the signed content limits the size -of message which can be processed due to memory restraints: a -streaming single pass option should be available. - -=head1 RETURN VALUES - -SMIME_read_PKCS7() returns a valid B<PKCS7> structure or B<NULL> -is 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_type(3)|PKCS7_type(3)> -L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -SMIME_read_PKCS7() was added to OpenSSL 0.9.5 - -=cut diff --git a/lib/libcrypto/doc/SMIME_write_PKCS7.pod b/lib/libcrypto/doc/SMIME_write_PKCS7.pod deleted file mode 100644 index 4a7cd08c424..00000000000 --- a/lib/libcrypto/doc/SMIME_write_PKCS7.pod +++ /dev/null @@ -1,65 +0,0 @@ -=pod - -=head1 NAME - -SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format. - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int SMIME_write_PKCS7(BIO *out, PKCS7 *p7, BIO *data, int flags); - -=head1 DESCRIPTION - -SMIME_write_PKCS7() adds the appropriate MIME headers to a PKCS#7 -structure to produce an S/MIME message. - -B<out> is the BIO to write the data to. B<p7> is the appropriate B<PKCS7> -structure. If streaming is enabled then the content must be supplied in the -B<data> argument. B<flags> is an optional set of flags. - -=head1 NOTES - -The following flags can be passed in the B<flags> parameter. - -If B<PKCS7_DETACHED> is set then cleartext signing will be used, -this option only makes sense for signedData where B<PKCS7_DETACHED> -is also set when PKCS7_sign() is also called. - -If the B<PKCS7_TEXT> flag is set MIME headers for type B<text/plain> -are added to the content, this only makes sense if B<PKCS7_DETACHED> -is also set. - -If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should -only be set if B<PKCS7_STREAM> was also set in the previous call to -PKCS7_sign() or B<PKCS7_encrypt()>. - -If cleartext signing is being used and B<PKCS7_STREAM> not set then -the data must be read twice: once to compute the signature in PKCS7_sign() -and once to output the S/MIME message. - -If streaming is performed the content is output in BER format using indefinite -length constructed encoding except in the case of signed data with detached -content where the content is absent and DER format is used. - -=head1 BUGS - -SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there -should be an option to disable this. - -=head1 RETURN VALUES - -SMIME_write_PKCS7() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> - -=head1 HISTORY - -SMIME_write_PKCS7() was added to OpenSSL 0.9.5 - -=cut diff --git a/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod b/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod deleted file mode 100644 index a37231e267b..00000000000 --- a/lib/libcrypto/doc/i2d_PKCS7_bio_stream.pod +++ /dev/null @@ -1,44 +0,0 @@ -=pod - -=head1 NAME - -i2d_PKCS7_bio_stream - output PKCS7 structure in BER format. - -=head1 SYNOPSIS - - #include <openssl/pkcs7.h> - - int i2d_PKCS7_bio_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); - -=head1 DESCRIPTION - -i2d_PKCS7_bio_stream() outputs a PKCS7 structure in BER format. - -It is otherwise identical to the function SMIME_write_PKCS7(). - -=head1 NOTES - -This function is effectively a version of the d2i_PKCS7_bio() supporting -streaming. - -=head1 BUGS - -The prefix "i2d" is arguably wrong because the function outputs BER format. - -=head1 RETURN VALUES - -i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, -L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, -L<PEM_write_bio_PKCS7_stream(3)|PEM_write_bio_PKCS7_stream(3)> - -=head1 HISTORY - -i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0 - -=cut diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 17efba0d080..dbfce916473 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.41 2016/11/03 12:21:50 schwarze Exp $ +# $OpenBSD: Makefile,v 1.42 2016/11/03 15:20:36 schwarze Exp $ .include <bsd.own.mk> # for NOMAN @@ -122,6 +122,18 @@ MAN= \ OPENSSL_config.3 \ OPENSSL_load_builtin_modules.3 \ OpenSSL_add_all_algorithms.3 \ + PEM_read_bio_PrivateKey.3 \ + PEM_write_bio_PKCS7_stream.3 \ + PKCS12_create.3 \ + PKCS12_parse.3 \ + PKCS5_PBKDF2_HMAC.3 \ + PKCS7_decrypt.3 \ + PKCS7_encrypt.3 \ + PKCS7_sign.3 \ + PKCS7_sign_add_signer.3 \ + PKCS7_verify.3 \ + SMIME_read_PKCS7.3 \ + SMIME_write_PKCS7.3 \ UI_new.3 \ bn_dump.3 \ crypto.3 \ @@ -129,19 +141,10 @@ MAN= \ d2i_PKCS8PrivateKey_bio.3 \ des_read_pw.3 \ evp.3 \ + i2d_PKCS7_bio_stream.3 \ lh_new.3 \ GENMAN= \ - PKCS5_PBKDF2_HMAC.3 \ - PEM_read_bio_PrivateKey.3 \ - PEM_write_bio_PKCS7_stream.3 \ - PKCS12_create.3 \ - PKCS12_parse.3 \ - PKCS7_decrypt.3 \ - PKCS7_encrypt.3 \ - PKCS7_sign.3 \ - PKCS7_sign_add_signer.3 \ - PKCS7_verify.3 \ RAND.3 \ RAND_add.3 \ RAND_bytes.3 \ @@ -164,8 +167,6 @@ GENMAN= \ RSA_sign_ASN1_OCTET_STRING.3 \ RSA_size.3 \ SHA1.3 \ - SMIME_read_PKCS7.3 \ - SMIME_write_PKCS7.3 \ X509_NAME_ENTRY_get_object.3 \ X509_NAME_add_entry_by_txt.3 \ X509_NAME_get_index_by_NID.3 \ @@ -193,7 +194,6 @@ GENMAN= \ dsa.3 \ ec.3 \ engine.3 \ - i2d_PKCS7_bio_stream.3 \ lh_stats.3 \ rsa.3 \ x509.3 \ diff --git a/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 new file mode 100644 index 00000000000..7dcea6dbe12 --- /dev/null +++ b/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 @@ -0,0 +1,997 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PEM_READ_BIO_PRIVATEKEY 3 +.Os +.Sh NAME +.Nm PEM , +.Nm PEM_read_bio_PrivateKey , +.Nm PEM_read_PrivateKey , +.Nm PEM_write_bio_PrivateKey , +.Nm PEM_write_PrivateKey , +.Nm PEM_write_bio_PKCS8PrivateKey , +.Nm PEM_write_PKCS8PrivateKey , +.Nm PEM_write_bio_PKCS8PrivateKey_nid , +.Nm PEM_write_PKCS8PrivateKey_nid , +.Nm PEM_read_bio_PUBKEY , +.Nm PEM_read_PUBKEY , +.Nm PEM_write_bio_PUBKEY , +.Nm PEM_write_PUBKEY , +.Nm PEM_read_bio_RSAPrivateKey , +.Nm PEM_read_RSAPrivateKey , +.Nm PEM_write_bio_RSAPrivateKey , +.Nm PEM_write_RSAPrivateKey , +.Nm PEM_read_bio_RSAPublicKey , +.Nm PEM_read_RSAPublicKey , +.Nm PEM_write_bio_RSAPublicKey , +.Nm PEM_write_RSAPublicKey , +.Nm PEM_read_bio_RSA_PUBKEY , +.Nm PEM_read_RSA_PUBKEY , +.Nm PEM_write_bio_RSA_PUBKEY , +.Nm PEM_write_RSA_PUBKEY , +.Nm PEM_read_bio_DSAPrivateKey , +.Nm PEM_read_DSAPrivateKey , +.Nm PEM_write_bio_DSAPrivateKey , +.Nm PEM_write_DSAPrivateKey , +.Nm PEM_read_bio_DSA_PUBKEY , +.Nm PEM_read_DSA_PUBKEY , +.Nm PEM_write_bio_DSA_PUBKEY , +.Nm PEM_write_DSA_PUBKEY , +.Nm PEM_read_bio_DSAparams , +.Nm PEM_read_DSAparams , +.Nm PEM_write_bio_DSAparams , +.Nm PEM_write_DSAparams , +.Nm PEM_read_bio_DHparams , +.Nm PEM_read_DHparams , +.Nm PEM_write_bio_DHparams , +.Nm PEM_write_DHparams , +.Nm PEM_read_bio_X509 , +.Nm PEM_read_X509 , +.Nm PEM_write_bio_X509 , +.Nm PEM_write_X509 , +.Nm PEM_read_bio_X509_AUX , +.Nm PEM_read_X509_AUX , +.Nm PEM_write_bio_X509_AUX , +.Nm PEM_write_X509_AUX , +.Nm PEM_read_bio_X509_REQ , +.Nm PEM_read_X509_REQ , +.Nm PEM_write_bio_X509_REQ , +.Nm PEM_write_X509_REQ , +.Nm PEM_write_bio_X509_REQ_NEW , +.Nm PEM_write_X509_REQ_NEW , +.Nm PEM_read_bio_X509_CRL , +.Nm PEM_read_X509_CRL , +.Nm PEM_write_bio_X509_CRL , +.Nm PEM_write_X509_CRL , +.Nm PEM_read_bio_PKCS7 , +.Nm PEM_read_PKCS7 , +.Nm PEM_write_bio_PKCS7 , +.Nm PEM_write_PKCS7 , +.Nm PEM_read_bio_NETSCAPE_CERT_SEQUENCE , +.Nm PEM_read_NETSCAPE_CERT_SEQUENCE , +.Nm PEM_write_bio_NETSCAPE_CERT_SEQUENCE , +.Nm PEM_write_NETSCAPE_CERT_SEQUENCE +.Nd PEM routines +.Sh SYNOPSIS +.In openssl/pem.h +.Ft EVP_PKEY * +.Fo PEM_read_bio_PrivateKey +.Fa "BIO *bp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EVP_PKEY * +.Fo PEM_read_PrivateKey +.Fa "FILE *fp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PrivateKey +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_PrivateKey +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS8PrivateKey +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_PKCS8PrivateKey +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "const EVP_CIPHER *enc" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS8PrivateKey_nid +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_PKCS8PrivateKey_nid +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fa "int nid" +.Fa "char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EVP_PKEY * +.Fo PEM_read_bio_PUBKEY +.Fa "BIO *bp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft EVP_PKEY * +.Fo PEM_read_PUBKEY +.Fa "FILE *fp" +.Fa "EVP_PKEY **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PUBKEY +.Fa "BIO *bp" +.Fa "EVP_PKEY *x" +.Fc +.Ft int +.Fo PEM_write_PUBKEY +.Fa "FILE *fp" +.Fa "EVP_PKEY *x" +.Fc +.Ft RSA * +.Fo PEM_read_bio_RSAPrivateKey +.Fa "BIO *bp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_RSAPrivateKey +.Fa "FILE *fp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_RSAPrivateKey +.Fa "BIO *bp" +.Fa "RSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_RSAPrivateKey +.Fa "FILE *fp" +.Fa "RSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_bio_RSAPublicKey +.Fa "BIO *bp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_RSAPublicKey +.Fa "FILE *fp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_RSAPublicKey +.Fa "BIO *bp" +.Fa "RSA *x" +.Fc +.Ft int +.Fo PEM_write_RSAPublicKey +.Fa "FILE *fp" +.Fa "RSA *x" +.Fc +.Ft RSA * +.Fo PEM_read_bio_RSA_PUBKEY +.Fa "BIO *bp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft RSA * +.Fo PEM_read_RSA_PUBKEY +.Fa "FILE *fp" +.Fa "RSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_RSA_PUBKEY +.Fa "BIO *bp" +.Fa "RSA *x" +.Fc +.Ft int +.Fo PEM_write_RSA_PUBKEY +.Fa "FILE *fp" +.Fa "RSA *x" +.Fc +.Ft DSA * +.Fo PEM_read_bio_DSAPrivateKey +.Fa "BIO *bp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_DSAPrivateKey +.Fa "FILE *fp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DSAPrivateKey +.Fa "BIO *bp" +.Fa "DSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_DSAPrivateKey +.Fa "FILE *fp" +.Fa "DSA *x" +.Fa "const EVP_CIPHER *enc" +.Fa "unsigned char *kstr" +.Fa "int klen" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_bio_DSA_PUBKEY +.Fa "BIO *bp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_DSA_PUBKEY +.Fa "FILE *fp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DSA_PUBKEY +.Fa "BIO *bp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo PEM_write_DSA_PUBKEY +.Fa "FILE *fp" +.Fa "DSA *x" +.Fc +.Ft DSA * +.Fo PEM_read_bio_DSAparams +.Fa "BIO *bp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DSA * +.Fo PEM_read_DSAparams +.Fa "FILE *fp" +.Fa "DSA **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DSAparams +.Fa "BIO *bp" +.Fa "DSA *x" +.Fc +.Ft int +.Fo PEM_write_DSAparams +.Fa "FILE *fp" +.Fa "DSA *x" +.Fc +.Ft DH * +.Fo PEM_read_bio_DHparams +.Fa "BIO *bp" +.Fa "DH **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft DH * +.Fo PEM_read_DHparams +.Fa "FILE *fp" +.Fa "DH **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_DHparams +.Fa "BIO *bp" +.Fa "DH *x" +.Fc +.Ft int +.Fo PEM_write_DHparams +.Fa "FILE *fp" +.Fa "DH *x" +.Fc +.Ft X509 * +.Fo PEM_read_bio_X509 +.Fa "BIO *bp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509 * +.Fo PEM_read_X509 +.Fa "FILE *fp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509 +.Fa "BIO *bp" +.Fa "X509 *x" +.Fc +.Ft int +.Fo PEM_write_X509 +.Fa "FILE *fp" +.Fa "X509 *x" +.Fc +.Ft X509 * +.Fo PEM_read_bio_X509_AUX +.Fa "BIO *bp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509 * +.Fo PEM_read_X509_AUX +.Fa "FILE *fp" +.Fa "X509 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509_AUX +.Fa "BIO *bp" +.Fa "X509 *x" +.Fc +.Ft int +.Fo PEM_write_X509_AUX +.Fa "FILE *fp" +.Fa "X509 *x" +.Fc +.Ft X509_REQ * +.Fo PEM_read_bio_X509_REQ +.Fa "BIO *bp" +.Fa "X509_REQ **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509_REQ * +.Fo PEM_read_X509_REQ +.Fa "FILE *fp" +.Fa "X509_REQ **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509_REQ +.Fa "BIO *bp" +.Fa "X509_REQ *x" +.Fc +.Ft int +.Fo PEM_write_X509_REQ +.Fa "FILE *fp" +.Fa "X509_REQ *x" +.Fc +.Ft int +.Fo PEM_write_bio_X509_REQ_NEW +.Fa "BIO *bp" +.Fa "X509_REQ *x" +.Fc +.Ft int +.Fo PEM_write_X509_REQ_NEW +.Fa "FILE *fp" +.Fa "X509_REQ *x" +.Fc +.Ft X509_CRL * +.Fo PEM_read_bio_X509_CRL +.Fa "BIO *bp" +.Fa "X509_CRL **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft X509_CRL * +.Fo PEM_read_X509_CRL +.Fa "FILE *fp" +.Fa "X509_CRL **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_X509_CRL +.Fa "BIO *bp" +.Fa "X509_CRL *x" +.Fc +.Ft int +.Fo PEM_write_X509_CRL +.Fa "FILE *fp" +.Fa "X509_CRL *x" +.Fc +.Ft PKCS7 * +.Fo PEM_read_bio_PKCS7 +.Fa "BIO *bp" +.Fa "PKCS7 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft PKCS7 * +.Fo PEM_read_PKCS7 +.Fa "FILE *fp" +.Fa "PKCS7 **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_PKCS7 +.Fa "BIO *bp" +.Fa "PKCS7 *x" +.Fc +.Ft int +.Fo PEM_write_PKCS7 +.Fa "FILE *fp" +.Fa "PKCS7 *x" +.Fc +.Ft NETSCAPE_CERT_SEQUENCE * +.Fo PEM_read_bio_NETSCAPE_CERT_SEQUENCE +.Fa "BIO *bp" +.Fa "NETSCAPE_CERT_SEQUENCE **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft NETSCAPE_CERT_SEQUENCE * +.Fo PEM_read_NETSCAPE_CERT_SEQUENCE +.Fa "FILE *fp" +.Fa "NETSCAPE_CERT_SEQUENCE **x" +.Fa "pem_password_cb *cb" +.Fa "void *u" +.Fc +.Ft int +.Fo PEM_write_bio_NETSCAPE_CERT_SEQUENCE +.Fa "BIO *bp" +.Fa "NETSCAPE_CERT_SEQUENCE *x" +.Fc +.Ft int +.Fo PEM_write_NETSCAPE_CERT_SEQUENCE +.Fa "FILE *fp" +.Fa "NETSCAPE_CERT_SEQUENCE *x" +.Fc +.Sh DESCRIPTION +The PEM functions read or write structures in PEM format. +In this sense PEM format is simply base64 encoded data surrounded by +header lines. +.Pp +For more details about the meaning of arguments see the +.Sx PEM function arguments +section. +.Pp +Each operation has four functions associated with it. +For clarity the term +.Dq Sy foobar No functions +will be used to collectively refer to the +.Fn PEM_read_bio_foobar , +.Fn PEM_read_foobar , +.Fn PEM_write_bio_foobar , +and +.Fn PEM_write_foobar +functions. +.Pp +The +.Sy PrivateKey +functions read or write a private key in PEM format using an +.Vt EVP_PKEY +structure. +The write routines use "traditional" private key format and can handle +both RSA and DSA private keys. +The read functions can additionally transparently handle PKCS#8 format +encrypted and unencrypted keys, too. +.Pp +.Fn PEM_write_bio_PKCS8PrivateKey +and +.Fn PEM_write_PKCS8PrivateKey +write a private key in an +.Vt EVP_PKEY +structure in PKCS#8 EncryptedPrivateKeyInfo format using PKCS#5 +v2.0 password based encryption algorithms. +The +.Fa enc +argument specifies the encryption algorithm to use: unlike all other PEM +routines, the encryption is applied at the PKCS#8 level and not in the +PEM headers. +If +.Fa enc +is +.Dv NULL , +then no encryption is used and a PKCS#8 PrivateKeyInfo structure +is used instead. +.Pp +.Fn PEM_write_bio_PKCS8PrivateKey_nid +and +.Fn PEM_write_PKCS8PrivateKey_nid +also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo. +However they use PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. +The algorithm to use is specified in the +.Fa nid +parameter and should be the NID of the corresponding OBJECT IDENTIFIER +(see NOTES section). +.Pp +The +.Sy PUBKEY +functions process a public key using an +.Vt EVP_PKEY +structure. +The public key is encoded as a SubjectPublicKeyInfo structure. +.Pp +The +.Sy RSAPrivateKey +functions process an RSA private key using an +.Vt RSA +structure. +They handle the same formats as the +.Sy PrivateKey +functions, but an error occurs if the private key is not RSA. +.Pp +The +.Sy RSAPublicKey +functions process an RSA public key using an +.Vt RSA +structure. +The public key is encoded using a PKCS#1 RSAPublicKey structure. +.Pp +The +.Sy RSA_PUBKEY +functions also process an RSA public key using an +.Vt RSA +structure. +However the public key is encoded using a SubjectPublicKeyInfo structure +and an error occurs if the public key is not RSA. +.Pp +The +.Sy DSAPrivateKey +functions process a DSA private key using a +.Vt DSA +structure. +They handle the same formats as the +.Sy PrivateKey +functions but an error occurs if the private key is not DSA. +.Pp +The +.Sy DSA_PUBKEY +functions process a DSA public key using a +.Vt DSA +structure. +The public key is encoded using a SubjectPublicKeyInfo structure and an +error occurs if the public key is not DSA. +.Pp +The +.Sy DSAparams +functions process DSA parameters using a +.Vt DSA +structure. +The parameters are encoded using a Dss-Parms structure as defined in RFC 2459. +.Pp +The +.Sy DHparams +functions process DH parameters using a +.Vt DH +structure. +The parameters are encoded using a PKCS#3 DHparameter structure. +.Pp +The +.Sy X509 +functions process an X509 certificate using an +.Vt X509 +structure. +They will also process a trusted X509 certificate but any trust settings +are discarded. +.Pp +The +.Sy X509_AUX +functions process a trusted X509 certificate using an +.Vt X509 +structure. +.Pp +The +.Sy X509_REQ +and +.Sy X509_REQ_NEW +functions process a PKCS#10 certificate request using an +.Vt X509_REQ +structure. +The +.Sy X509_REQ +write functions use CERTIFICATE REQUEST in the header whereas the +.Sy X509_REQ_NEW +functions use NEW CERTIFICATE REQUEST (as required by some CAs). +The +.Sy X509_REQ +read functions will handle either form so there are no +.Sy X509_REQ_NEW +read functions. +.Pp +The +.Sy X509_CRL +functions process an X509 CRL using an +.Vt X509_CRL +structure. +.Pp +The +.Sy PKCS7 +functions process a PKCS#7 ContentInfo using a +.Vt PKCS7 +structure. +.Pp +The +.Sy NETSCAPE_CERT_SEQUENCE +functions process a Netscape Certificate Sequence using a +.Vt NETSCAPE_CERT_SEQUENCE +structure. +.Pp +The old +.Sy PrivateKey +write routines are retained for compatibility. +New applications should write private keys using the +.Fn PEM_write_bio_PKCS8PrivateKey +or +.Fn PEM_write_PKCS8PrivateKey +routines because they are more secure (they use an iteration count of +2048 whereas the traditional routines use a count of 1) unless +compatibility with older versions of OpenSSL is important. +.Pp +The +.Sy PrivateKey +read routines can be used in all applications because they handle all +formats transparently. +.Ss PEM function arguments +The PEM functions have many common arguments. +.Pp +The +.Fa bp +parameter specifies the +.Vt BIO +to read from or write to. +.Pp +The +.Fa fp +parameter specifies the +.Vt FILE +pointer to read from or write to. +.Pp +The PEM read functions all take a pointer to pointer argument +.Fa x +and return a pointer of the same type. +If +.Fa x +is +.Dv NULL , +then the parameter is ignored. +If +.Fa x +is not +.Dv NULL +but +.Pf * Fa x +is +.Dv NULL , +then the structure returned will be written to +.Pf * Fa x . +If neither +.Fa x +nor +.Pf * Fa x +are +.Dv NULL , +then an attempt is made to reuse the structure at +.Pf * Fa x , +but see the +.Sx BUGS +and +.Sx EXAMPLES +sections. +Irrespective of the value of +.Fa x , +a pointer to the structure is always returned, or +.Dv NULL +if an error occurred. +.Pp +The PEM functions which write private keys take an +.Fa enc +parameter which specifies the encryption algorithm to use. +Encryption is done at the PEM level. +If this parameter is set to +.Dv NULL , +then the private key is written in unencrypted form. +.Pp +The +.Fa cb +argument is the callback to use when querying for the passphrase used +for encrypted PEM structures (normally only private keys). +.Pp +For the PEM write routines, if the +.Fa kstr +parameter is not +.Dv NULL , +then +.Fa klen +bytes at +.Fa kstr +are used as the passphrase and +.Fa cb +is ignored. +.Pp +If the +.Fa cb +parameters is set to +.Dv NULL +and the +.Fa u +parameter is not +.Dv NULL , +then the +.Fa u +parameter is interpreted as a null terminated string to use as the +passphrase. +If both +.Fa cb +and +.Fa u +are +.Dv NULL , +then the default callback routine is used which will typically +prompt for the passphrase on the current terminal with echoing +turned off. +.Pp +The default passphrase callback is sometimes inappropriate (for example +in a GUI application) so an alternative can be supplied. +The callback routine has the following form: +.Bd -filled -offset inset +.Ft int +.Fo cb +.Fa "char *buf" +.Fa "int size" +.Fa "int rwflag" +.Fa "void *u" +.Fc +.Ed +.Pp +.Fa buf +is the buffer to write the passphrase to. +.Fa size +is the maximum length of the passphrase, i.e. the size of +.Fa buf . +.Fa rwflag +is a flag which is set to 0 when reading and 1 when writing. +A typical routine will ask the user to verify the passphrase (for +example by prompting for it twice) if +.Fa rwflag +is 1. +The +.Fa u +parameter has the same value as the +.Fa u +parameter passed to the PEM routine. +It allows arbitrary data to be passed to the callback by the application +(for example a window handle in a GUI application). +The callback must return the number of characters in the passphrase +or 0 if an error occurred. +.Ss PEM encryption format +This old +.Sy PrivateKey +routines use a non standard technique for encryption. +.Pp +The private key (or other data) takes the following form: +.Bd -literal -offset indent +-----BEGIN RSA PRIVATE KEY----- +Proc-Type: 4,ENCRYPTED +DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89 + +\&...base64 encoded data... +-----END RSA PRIVATE KEY----- +.Ed +.Pp +The line beginning with +.Dq DEK-Info +contains two comma separated pieces of information: +the encryption algorithm name as used by +.Xr EVP_get_cipherbyname 3 +and an 8 byte salt encoded as a set of hexadecimal digits. +.Pp +After this is the base64 encoded encrypted data. +.Pp +The encryption key is determined using +.Xr EVP_BytesToKey 3 , +using the salt and an iteration count of 1. +The IV used is the value of the salt and *not* the IV returned by +.Xr EVP_BytesToKey 3 . +.Sh RETURN VALUES +The read routines return either a pointer to the structure read or +.Dv NULL +if an error occurred. +.Pp +The write routines return 1 for success or 0 for failure. +.Sh EXAMPLES +Although the PEM routines take several arguments, in almost all +applications most of them are set to 0 or +.Dv NULL . +.Pp +Read a certificate in PEM format from a +.Vt BIO : +.Bd -literal +X509 *x; +x = PEM_read_bio_X509(bp, NULL, 0, NULL); +if (x == NULL) { + /* Error */ +} +.Ed +.Pp +Alternative method: +.Bd -literal +X509 *x = NULL; +if (!PEM_read_bio_X509(bp, &x, 0, NULL)) { + /* Error */ +} +.Ed +.Pp +Write a certificate to a +.Vt BIO : +.Bd -literal +if (!PEM_write_bio_X509(bp, x)) { + /* Error */ +} +.Ed +.Pp +Write an unencrypted private key to a +.Vt FILE : +.Bd -literal +if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) { + /* Error */ +} +.Ed +.Pp +Write a private key (using traditional format) to a +.Vt BIO +using triple DES encryption, the pass phrase is prompted for: +.Bd -literal +if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), + NULL, 0, 0, NULL)) { + /* Error */ +} +.Ed +.Pp +Write a private key (using PKCS#8 format) to a +.Vt BIO +using triple DES encryption, using the pass phrase "hello": +.Bd -literal +if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), + NULL, 0, 0, "hello")) { + /* Error */ +} +.Ed +.Pp +Read a private key from a +.Vt BIO +using the pass phrase "hello": +.Bd -literal +key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); +if (key == NULL) { + /* Error */ +} +.Ed +.Pp +Read a private key from a +.Vt BIO +using a pass phrase callback: +.Bd -literal +key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key"); +if (key == NULL) { + /* Error */ +} +.Ed +.Pp +Skeleton pass phrase callback: +.Bd -literal +int +pass_cb(char *buf, int size, int rwflag, void *u) +{ + int len; + char *tmp; + + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \e"%s\e"\en", u); + + /* get pass phrase, length 'len' into 'tmp' */ + tmp = "hello"; + len = strlen(tmp); + + if (len == 0) + return 0; + /* if too long, truncate */ + if (len > size) + len = size; + memcpy(buf, tmp, len); + return len; +} +.Ed +.Sh CAVEATS +A frequent cause of problems is attempting to use the PEM routines like +this: +.Bd -literal +X509 *x; +PEM_read_bio_X509(bp, &x, 0, NULL); +.Ed +.Pp +This is a bug because an attempt will be made to reuse the data at +.Fa x +which is an uninitialised pointer. +.Sh BUGS +The PEM read routines in some versions of OpenSSL will not correctly +reuse an existing structure. +Therefore +.Pp +.Dl PEM_read_bio_X509(bp, &x, 0, NULL); +.Pp +where +.Fa x +already contains a valid certificate may not work, whereas +.Bd -literal -offset indent +X509_free(x); +x = PEM_read_bio_X509(bp, NULL, 0, NULL); +.Ed +.Pp +is guaranteed to work. diff --git a/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 b/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 new file mode 100644 index 00000000000..12d556558d7 --- /dev/null +++ b/lib/libcrypto/man/PEM_write_bio_PKCS7_stream.3 @@ -0,0 +1,40 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PEM_WRITE_BIO_PKCS7_STREAM 3 +.Os +.Sh NAME +.Nm PEM_write_bio_PKCS7_stream +.Nd output PKCS7 structure in PEM format +.Sh SYNOPSIS +.In openssl/pkcs7.h +.In openssl/pem.h +.Ft int +.Fo PEM_write_bio_PKCS7_stream +.Fa "BIO *out" +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PEM_write_bio_PKCS7_stream +outputs a PKCS7 structure in PEM format. +.Pp +It is otherwise identical to the function +.Xr SMIME_write_PKCS7 3 . +.Pp +This function is effectively a version of the +.Xr PEM_write_bio_PKCS7 3 +supporting streaming. +.Sh RETURN VALUES +.Fn PEM_write_bio_PKCS7_stream +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr PKCS7_decrypt 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_verify 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn PEM_write_bio_PKCS7_stream +was added to OpenSSL 1.0.0. diff --git a/lib/libcrypto/man/PKCS12_create.3 b/lib/libcrypto/man/PKCS12_create.3 new file mode 100644 index 00000000000..0a7f0c2ab59 --- /dev/null +++ b/lib/libcrypto/man/PKCS12_create.3 @@ -0,0 +1,122 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PKCS12_CREATE 3 +.Os +.Sh NAME +.Nm PKCS12_create +.Nd create a PKCS#12 structure +.Sh SYNOPSIS +.In openssl/pkcs12.h +.Ft PKCS12 * +.Fo PKCS12_create +.Fa "char *pass" +.Fa "char *name" +.Fa "EVP_PKEY *pkey" +.Fa "X509 *cert" +.Fa "STACK_OF(X509) *ca" +.Fa "int nid_key" +.Fa "int nid_cert" +.Fa "int iter" +.Fa "int mac_iter" +.Fa "int keytype" +.Fc +.Sh DESCRIPTION +.Fn PKCS12_create +creates a PKCS#12 structure. +.Pp +.Fa pass +is the passphrase to use. +.Fa name +is the +.Sy friendlyName +to use for the supplied certificate and key. +.Fa pkey +is the private key to include in the structure and +.Fa cert +its corresponding certificates. +.Fa ca +is an optional set of certificates to also include in the structure. +.Fa pkey , +.Fa cert , +or both can be +.Dv NULL +to indicate that no key or certificate is required. +.Pp +.Fa nid_key +and +.Fa nid_cert +are the encryption algorithms that should be used for the key and +certificate, respectively. +If either +.Fa nid_key +or +.Fa nid_cert +is set to -1, no encryption will be used. +.Pp +.Fa iter +is the encryption algorithm iteration count to use and +.Fa mac_iter +is the MAC iteration count to use. +If +.Fa mac_iter +is set to -1, the MAC will be omitted entirely. +.Pp +.Fa keytype +is the type of key. +.Pp +The parameters +.Fa nid_key , +.Fa nid_cert , +.Fa iter , +.Fa mac_iter , +and +.Fa keytype +can all be set to zero and sensible defaults will be used. +.Pp +These defaults are: 40 bit RC2 encryption for certificates, triple DES +encryption for private keys, a key iteration count of +PKCS12_DEFAULT_ITER (currently 2048) and a MAC iteration count of 1. +.Pp +The default MAC iteration count is 1 in order to retain compatibility +with old software which did not interpret MAC iteration counts. +If such compatibility is not required then +.Fa mac_iter +should be set to PKCS12_DEFAULT_ITER. +.Pp +.Fa keytype +adds a flag to the store private key. +This is a non standard extension that is only currently interpreted by +MSIE. +If set to zero the flag is omitted, if set to +.Dv KEY_SIG +the key can be used for signing only, and if set to +.Dv KEY_EX +it can be used for signing and encryption. +This option was useful for old export grade software which could use +signing only keys of arbitrary size but had restrictions on the +permissible sizes of keys which could be used for encryption. +.Pp +If a certificate contains an +.Sy alias +or +.Sy keyid +then this will be used for the corresponding +.Sy friendlyName +or +.Sy localKeyID +in the PKCS12 structure. +.Sh SEE ALSO +.Xr d2i_PKCS12 3 +.Sh HISTORY +PKCS12_create was added in OpenSSL 0.9.3. +.Pp +Before OpenSSL 0.9.8, neither +.Fa pkey +nor +.Fa cert +were allowed to be +.Dv NULL , +and a value of -1 was not allowed for +.Fa nid_key , +.Fa nid_cert , +and +.Fa mac_iter . diff --git a/lib/libcrypto/man/PKCS12_parse.3 b/lib/libcrypto/man/PKCS12_parse.3 new file mode 100644 index 00000000000..6930bdf3398 --- /dev/null +++ b/lib/libcrypto/man/PKCS12_parse.3 @@ -0,0 +1,90 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PKCS12_PARSE 3 +.Os +.Sh NAME +.Nm PKCS12_parse +.Nd parse a PKCS#12 structure +.Sh SYNOPSIS +.In openssl/pkcs12.h +.Ft int +.Fo PKCS12_parse +.Fa "PKCS12 *p12" +.Fa "const char *pass" +.Fa "EVP_PKEY **pkey" +.Fa "X509 **cert" +.Fa "STACK_OF(X509) **ca" +.Fc +.Sh DESCRIPTION +.Fn PKCS12_parse +parses a PKCS12 structure. +.Pp +.Fa p12 +is the +.Vt PKCS12 +structure to parse. +.Fa pass +is the passphrase to use. +If successful, the private key will be written to +.Pf * Fa pkey , +the corresponding certificate to +.Pf * Fa cert , +and any additional certificates to +.Pf * Fa ca . +.Pp +The parameters +.Fa pkey +and +.Fa cert +cannot be +.Dv NULL . +.Fa ca +can be +.Dv NULL , +in which case additional certificates will be discarded. +.Pf * Fa ca +can also be a valid STACK in which case additional certificates are +appended to +.Pf * Fa ca . +If +.Pf * Fa ca +is +.Dv NULL , +a new STACK will be allocated. +.Pp +The +.Sy friendlyName +and +.Sy localKeyID +attributes (if present) of each certificate will be stored in the +.Fa alias +and +.Fa keyid +attributes of the +.Vt X509 +structure. +.Sh RETURN VALUES +.Fn PKCS12_parse +returns 1 for success and 0 if an error occurred. +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr d2i_PKCS12 3 +.Sh HISTORY +PKCS12_parse was added in OpenSSL 0.9.3. +.Sh BUGS +Only a single private key and corresponding certificate is returned by +this function. +More complex PKCS#12 files with multiple private keys will only return +the first match. +.Pp +Only +.Sy friendlyName +and +.Sy localKeyID +attributes are currently stored in certificates. +Other attributes are discarded. +.Pp +Attributes currently cannot be stored in the private key +.Vt EVP_PKEY +structure. diff --git a/lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3 b/lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3 new file mode 100644 index 00000000000..333e45250eb --- /dev/null +++ b/lib/libcrypto/man/PKCS5_PBKDF2_HMAC.3 @@ -0,0 +1,106 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PKCS5_PBKDF2_HMAC 3 +.Os +.Sh NAME +.Nm PKCS5_PBKDF2_HMAC , +.Nm PKCS5_PBKDF2_HMAC_SHA1 +.Nd password based derivation routines with salt and iteration count +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo PKCS5_PBKDF2_HMAC +.Fa "const char *pass" +.Fa "int passlen" +.Fa "const unsigned char *salt" +.Fa "int saltlen" +.Fa "int iter" +.Fa "const EVP_MD *digest" +.Fa "int keylen" +.Fa "unsigned char *out" +.Fc +.Ft int +.Fo PKCS5_PBKDF2_HMAC_SHA1 +.Fa "const char *pass" +.Fa "int passlen" +.Fa "const unsigned char *salt" +.Fa "int saltlen" +.Fa "int iter" +.Fa "int keylen" +.Fa "unsigned char *out" +.Fc +.Sh DESCRIPTION +.Fn PKCS5_PBKDF2_HMAC +derives a key from a password using a salt and iteration count as +specified in RFC 2898. +.Pp +.Fa pass +is the password used in the derivation of length +.Fa passlen . +.Fa pass +is an optional parameter and can be +.Dv NULL . +If +.Fa passlen +is -1, then the function will calculate the length of +.Fa pass +using +.Xr strlen 3 . +.Pp +.Fa salt +is the salt used in the derivation of length +.Fa saltlen . +If the +.Fa salt +is +.Dv NULL , +then +.Fa saltlen +must be 0. +The function will not attempt to calculate the length of the +.Fa salt +because it is not assumed to be NUL terminated. +.Pp +.Fa iter +is the iteration count and its value should be greater than or equal to 1. +RFC 2898 suggests an iteration count of at least 1000. +Any +.Fa iter +less than 1 is treated as a single iteration. +.Pp +.Fa digest +is the message digest function used in the derivation. +Values include any of the EVP_* message digests. +.Fn PKCS5_PBKDF2_HMAC_SHA1 +calls +.Fn PKCS5_PBKDF2_HMAC +with +.Xr EVP_sha1 3 . +.Pp +The derived key will be written to +.Fa out . +The size of the +.Fa out +buffer is specified via +.Fa keylen . +.Pp +A typical application of this function is to derive keying material for +an encryption algorithm from a password in the +.Fa pass , +a salt in +.Fa salt , +and an iteration count. +.Pp +Increasing the +.Fa iter +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. +.Sh RETURN VALUES +.Fn PKCS5_PBKDF2_HMAC +and +.Fn PBKCS5_PBKDF2_HMAC_SHA1 +return 1 on success or 0 on error. +.Sh SEE ALSO +.Xr evp 3 , +.Xr EVP_BytesToKey 3 , +.Xr rand 3 diff --git a/lib/libcrypto/man/PKCS7_decrypt.3 b/lib/libcrypto/man/PKCS7_decrypt.3 new file mode 100644 index 00000000000..e69de29bb2d --- /dev/null +++ b/lib/libcrypto/man/PKCS7_decrypt.3 diff --git a/lib/libcrypto/man/PKCS7_encrypt.3 b/lib/libcrypto/man/PKCS7_encrypt.3 new file mode 100644 index 00000000000..860a9181b8d --- /dev/null +++ b/lib/libcrypto/man/PKCS7_encrypt.3 @@ -0,0 +1,113 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PKCS7_ENCRYPT 3 +.Os +.Sh NAME +.Nm PKCS7_encrypt +.Nd create a PKCS#7 envelopedData structure +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fo PKCS7_encrypt +.Fa "STACK_OF(X509) *certs" +.Fa "BIO *in" +.Fa "const EVP_CIPHER *cipher" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_encrypt +creates and returns a PKCS#7 envelopedData structure. +.Fa certs +is a list of recipient certificates. +.Fa in +is the content to be encrypted. +.Fa cipher +is the symmetric cipher to use. +.Fa flags +is an optional set of flags. +.Pp +Only RSA keys are supported in PKCS#7 and envelopedData so the recipient +certificates supplied to this function must all contain RSA public keys, +though they do not have to be signed using the RSA algorithm. +.Pp +The algorithm passed in the +.Fa cipher +parameter must support ASN1 encoding of its parameters. +.Pp +Many browsers implement a "sign and encrypt" option which is simply an +S/MIME envelopedData containing an S/MIME signed message. +This can be readily produced by storing the S/MIME signed message in a +memory +.Vt BIO +and passing it to +.Fn PKCS7_encrypt . +.Pp +The following flags can be passed in the +.Fa flags +parameter. +.Pp +If the +.Dv PKCS7_TEXT +flag is set, MIME headers for type +.Sy text/plain +are prepended to the data. +.Pp +Normally the supplied content is translated into MIME canonical format +(as required by the S/MIME specifications). +If +.Dv 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. +If +.Dv PKCS7_BINARY +is set, then +.Dv PKCS7_TEXT +is ignored. +.Pp +If the +.Dv PKCS7_STREAM +flag is set, a partial +.Vt PKCS7 +structure is output suitable for streaming I/O: no data is read from +.Fa in . +.Pp +If the flag +.Dv PKCS7_STREAM +is set, the returned +.Vt PKCS7 +structure is +.Sy not +complete and outputting its contents via a function that does not +properly finalize the +.Vt PKCS7 +structure will give unpredictable results. +.Pp +Several functions including +.Xr SMIME_write_PKCS7 3 , +.Xr i2d_PKCS7_bio_stream 3 , +and +.Xr PEM_write_bio_PKCS7_stream 3 +finalize the structure. +Alternatively finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_PKCS7 3 . +.Sh RETURN VALUES +.Fn PKCS7_encrypt +returns either a +.Vt PKCS7 +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr PKCS7_decrypt 3 +.Sh HISTORY +.Xr PKCS7_decrypt 3 +was added to OpenSSL 0.9.5. +The +.Dv PKCS7_STREAM +flag was first supported in OpenSSL 1.0.0. diff --git a/lib/libcrypto/man/PKCS7_sign.3 b/lib/libcrypto/man/PKCS7_sign.3 new file mode 100644 index 00000000000..894472402d1 --- /dev/null +++ b/lib/libcrypto/man/PKCS7_sign.3 @@ -0,0 +1,190 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PKCS7_SIGN 3 +.Os +.Sh NAME +.Nm PKCS7_sign +.Nd create a PKCS#7 signedData structure +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fo PKCS7_sign +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "STACK_OF(X509) *certs" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_sign +creates and returns a PKCS#7 signedData structure. +.Fa signcert +is the certificate to sign with, +.Fa pkey +is the corresponding private key. +.Fa certs +is an optional additional set of certificates to include in the PKCS#7 +structure (for example any intermediate CAs in the chain). +.Pp +The data to be signed is read from +.Vt BIO +.Fa data . +.Pp +.Fa flags +is an optional set of flags. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter. +.Pp +Many S/MIME clients expect the signed content to include valid MIME +headers. +If the +.Dv PKCS7_TEXT +flag is set, MIME headers for type +.Sy text/plain +are prepended to the data. +.Pp +If +.Dv 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 +.Fa 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. +.Pp +The data being signed is included in the +.Vt PKCS7 +structure, unless +.Dv 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. +.Pp +Normally the supplied content is translated into MIME canonical format +(as required by the S/MIME specifications). +If +.Dv 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. +.Pp +The signedData structure includes several PKCS#7 authenticatedAttributes +including the signing time, the PKCS#7 content type and the supported +list of ciphers in an SMIMECapabilities attribute. +If +.Dv PKCS7_NOATTR +is set, then no authenticatedAttributes will be used. +If +.Dv PKCS7_NOSMIMECAP +is set, then just the SMIMECapabilities are omitted. +.Pp +If present, the SMIMECapabilities attribute indicates support for the +following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 +bit RC2. +If any of these algorithms is disabled then it will not be included. +.Pp +If the flags +.Dv PKCS7_STREAM +is set, then the returned +.Vt PKCS7 +structure is just initialized ready to perform the signing operation. +The signing is however +.Sy not +performed and the data to be signed is not read from the +.Fa data +parameter. +Signing is deferred until after the data has been written. +In this way data can be signed in a single pass. +.Pp +If the +.Dv PKCS7_PARTIAL +flag is set, a partial +.Vt PKCS7 +structure is output to which additional signers and capabilities can be +added before finalization. +.Pp +If the flag +.Dv PKCS7_STREAM +is set, the returned +.Vt PKCS7 +structure is +.Sy not +complete and outputting its contents via a function that does not +properly finalize the +.Vt PKCS7 +structure will give unpredictable results. +.Pp +Several functions including +.Xr SMIME_write_PKCS7 3 , +.Xr i2d_PKCS7_bio_stream 3 , +.Xr PEM_write_bio_PKCS7_stream 3 +finalize the structure. +Alternatively finalization can be performed by obtaining the streaming +ASN1 +.Vt BIO +directly using +.Xr BIO_new_PKCS7 3 . +.Pp +If a signer is specified, it will use the default digest for the +signing algorithm. +This is +.Sy SHA1 +for both RSA and DSA keys. +.Pp +In OpenSSL 1.0.0, the +.Fa certs , +.Fa signcert , +and +.Fa pkey +parameters can all be +.Dv NULL +if the +.Dv PKCS7_PARTIAL +flag is set. +One or more signers can be added using the function +.Xr PKCS7_sign_add_signer 3. +.Xr PKCS7_final 3 +must also be called to finalize the structure if streaming is not +enabled. +Alternative signing digests can also be specified using this method. +.Pp +In OpenSSL 1.0.0, if +.Fa signcert +and +.Fa pkey +are +.Dv NULL , +then a certificates only PKCS#7 structure is output. +.Pp +In versions of OpenSSL before 1.0.0 the +.Fa signcert +and +.Fa pkey +parameters must +.Sy NOT +be +.Dv NULL . +.Sh RETURN VALUES +.Fn PKCS7_sign +returns either a valid +.Vt PKCS7 +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Fn ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr PKCS7_verify 3 +.Sh HISTORY +.Fn PKCS7_sign +was added to OpenSSL 0.9.5. +.Pp +The +.Dv PKCS7_PARTIAL +and +.Dv PKCS7_STREAM +flags were added in OpenSSL 1.0.0. +.Sh BUGS +Some advanced attributes such as counter signatures are not supported. diff --git a/lib/libcrypto/man/PKCS7_sign_add_signer.3 b/lib/libcrypto/man/PKCS7_sign_add_signer.3 new file mode 100644 index 00000000000..b20b6b91e62 --- /dev/null +++ b/lib/libcrypto/man/PKCS7_sign_add_signer.3 @@ -0,0 +1,128 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PKCS7_SIGN_ADD_SIGNER 3 +.Os +.Sh NAME +.Nm PKCS7_sign_add_signer +.Nd add a signer PKCS7 signed data structure +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft PKCS7_SIGNER_INFO * +.Fo PKCS7_sign_add_signer +.Fa "PKCS7 *p7" +.Fa "X509 *signcert" +.Fa "EVP_PKEY *pkey" +.Fa "const EVP_MD *md" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_sign_add_signer +adds a signer with certificate +.Fa signcert +and private key +.Fa pkey +using message digest +.Fa md +to a +.Vt PKCS7 +signed data structure +.Fa p7 . +.Pp +The +.Vt PKCS7 +structure should be obtained from an initial call to +.Xr PKCS7_sign 3 +with the flag +.Dv PKCS7_PARTIAL +set, or in the case or re-signing, a valid +.Vt PKCS7 +signed data structure. +.Pp +If the +.Fa md +parameter is +.Dv NULL , +then the default digest for the public key algorithm will be used. +.Pp +Unless the +.Dv PKCS7_REUSE_DIGEST +flag is set, the returned +.Dv PKCS7 +structure is not complete and must be +finalized either by streaming (if applicable) or by a call to +.Xr PKCS7_final 3 . +.Pp +The main purpose of this function is to provide finer control over a +PKCS#7 signed data structure where the simpler +.Xr PKCS7_sign 3 +function defaults are not appropriate, for example if multiple +signers or non default digest algorithms are needed. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter. +.Pp +If +.Dv PKCS7_REUSE_DIGEST +is set, then an attempt is made to copy the content digest value from the +.Vt PKCS7 +structure: to add a signer to an existing structure. +An error occurs if a matching digest value cannot be found to copy. +The returned +.Vt PKCS7 +structure will be valid and finalized when this flag is set. +.Pp +If +.Dv PKCS7_PARTIAL +is set in addition to +.Dv PKCS7_REUSE_DIGEST , +then the +.Dv PKCS7_SIGNER_INO +structure will not be finalized, so additional attributes can be added. +In this case an explicit call to +.Xr PKCS7_SIGNER_INFO_sign 3 +is needed to finalize it. +.Pp +If +.Dv PKCS7_NOCERTS +is set, the signer's certificate will not be included in the +.Vt PKCS7 +structure, the signer's certificate must still be supplied in the +.Fa 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. +.Pp +The signedData structure includes several PKCS#7 authenticatedAttributes +including the signing time, the PKCS#7 content type and the supported +list of ciphers in an SMIMECapabilities attribute. +If +.Dv PKCS7_NOATTR +is set, then no authenticatedAttributes will be used. +If +.Dv PKCS7_NOSMIMECAP +is set, then just the SMIMECapabilities are omitted. +.Pp +If present, the SMIMECapabilities attribute indicates support for the +following algorithms: triple DES, 128 bit RC2, 64 bit RC2, DES and 40 +bit RC2. +If any of these algorithms is disabled, then it will not be included. +.Pp +.Fn PKCS7_sign_add_signer +returns an internal pointer to the +.Vt PKCS7_SIGNER_INFO +structure just added, this can be used to set additional attributes +before it is finalized. +.Sh RETURN VALUES +.Fn PKCS7_sign_add_signer +returns an internal pointer to the +.Vt PKCS7_SIGNER_INFO +structure just added or +.Dv NULL +if an error occurs. +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr PKCS7_final 3 , +.Xr PKCS7_sign 3 +.Sh HISTORY +.Xr PKCS7_sign_add_signer 3 +was added to OpenSSL 1.0.0. diff --git a/lib/libcrypto/man/PKCS7_verify.3 b/lib/libcrypto/man/PKCS7_verify.3 new file mode 100644 index 00000000000..3cc6cbac669 --- /dev/null +++ b/lib/libcrypto/man/PKCS7_verify.3 @@ -0,0 +1,193 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt PKCS7_VERIFY 3 +.Os +.Sh NAME +.Nm PKCS7_verify , +.Nm PKCS7_get0_signers +.Nd verify a PKCS#7 signedData structure +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft int +.Fo PKCS7_verify +.Fa "PKCS7 *p7" +.Fa "STACK_OF(X509) *certs" +.Fa "X509_STORE *store" +.Fa "BIO *indata" +.Fa "BIO *out" +.Fa "int flags" +.Fc +.Ft STACK_OF(X509) * +.Fo PKCS7_get0_signers +.Fa "PKCS7 *p7" +.Fa "STACK_OF(X509) *certs" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn PKCS7_verify +verifies a PKCS#7 signedData structure. +.Fa p7 +is the +.Vt PKCS7 +structure to verify. +.Fa certs +is a set of certificates in which to search for the signer's +certificate. +.Fa store +is a trusted certificate store (used for chain verification). +.Fa indata +is the signed data if the content is not present in +.Fa p7 , +that is if it is detached. +The content is written to +.Fa out +if it is not +.Dv NULL . +.Pp +.Fa flags +is an optional set of flags, which can be used to modify the verify +operation. +.Pp +.Fn PKCS7_get0_signers +retrieves the signer's certificates from +.Fa p7 . +It does +.Sy not +check their validity or whether any signatures are valid. +The +.Fa certs +and +.Fa flags +parameters have the same meanings as in +.Fn PKCS7_verify . +.Pp +Normally the verify process proceeds as follows. +.Pp +Initially some sanity checks are performed on +.Fa p7 . +The type of +.Fa p7 +must be signedData. +There must be at least one signature on the data and if the content +is detached, +.Fa indata +cannot be +.Dv NULL . +.Pp +An attempt is made to locate all the signer's certificates, first +looking in the +.Fa certs +parameter (if it is not +.Dv NULL ) +and then looking in any certificates contained in the +.Fa p7 +structure itself. +If any signer's certificates cannot be located the operation fails. +.Pp +Each signer's certificate is chain verified using the +.Sy smimesign +purpose and the supplied trusted certificate store. +Any internal certificates in the message are used as untrusted CAs. +If any chain verify fails an error code is returned. +.Pp +Finally, the signed content is read (and written to +.Fa out +is it is not +.Dv NULL ) +and the signature's checked. +.Pp +If all signature's verify correctly then the function is successful. +.Pp +Any of the following flags (OR'ed together) can be passed in the +.Fa flags +parameter to change the default verify behaviour. +Only the flag +.Dv PKCS7_NOINTERN +is meaningful to +.Fn PKCS7_get0_signers . +.Pp +If +.Dv PKCS7_NOINTERN +is set, the certificates in the message itself are not searched when +locating the signer's certificate. +This means that all the signer's certificates must be in the +.Fa certs +parameter. +.Pp +If the +.Dv PKCS7_TEXT +flag is set, MIME headers for type +.Sy text/plain +are deleted from the content. +If the content is not of type +.Sy text/plain , +then an error is returned. +.Pp +If +.Dv PKCS7_NOVERIFY +is set, the signer's certificates are not chain verified. +.Pp +If +.Dv PKCS7_NOCHAIN +is set, then the certificates contained in the message are not used as +untrusted CAs. +This means that the whole verify chain (apart from the signer's +certificate) must be contained in the trusted store. +.Pp +If +.Dv PKCS7_NOSIGS +is set, then the signatures on the data are not checked. +.Pp +One application of +.Dv PKCS7_NOINTERN +is to only accept messages signed by a small number of certificates. +The acceptable certificates would be passed in the +.Fa certs +parameter. +In this case, if the signer is not one of the certificates supplied in +.Fa certs , +then the verify will fail because the signer cannot be found. +.Pp +Care should be taken when modifying the default verify behaviour, for +example setting +.Dv PKCS7_NOVERIFY | PKCS7_NOSIGS +will totally disable all verification and any signed message will be +considered valid. +This combination is however useful if one merely wishes to write the +content to +.Fa out +and its validity is not considered important. +.Pp +Chain verification should arguably be performed using the signing time +rather than the current time. +However since the signing time is supplied by the signer, it cannot be +trusted without additional evidence (such as a trusted timestamp). +.Sh RETURN VALUES +.Fn PKCS7_verify +returns 1 for a successful verification and 0 or a negative value if +an error occurs. +.Pp +.Fn PKCS7_get0_signers +returns all signers or +.Dv NULL +if an error occurred. +.Pp +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr PKCS7_sign 3 +.Sh HISTORY +.Fn PKCS7_verify +was added to OpenSSL 0.9.5 . +.Sh BUGS +The trusted certificate store is not searched for the signer's +certificate. +This is primarily due to the inadequacies of the current +.Vt X509_STORE +functionality. +.Pp +The lack of single pass processing and the need to hold all data +in memory as mentioned in +.Xr PKCS7_sign 3 +also applies to +.Fn PKCS7_verify . diff --git a/lib/libcrypto/man/SMIME_read_PKCS7.3 b/lib/libcrypto/man/SMIME_read_PKCS7.3 new file mode 100644 index 00000000000..2e7fcb514c2 --- /dev/null +++ b/lib/libcrypto/man/SMIME_read_PKCS7.3 @@ -0,0 +1,101 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt SMIME_READ_PKCS7 3 +.Os +.Sh NAME +.Nm SMIME_read_PKCS7 +.Nd parse S/MIME message +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft PKCS7 * +.Fo SMIME_read_PKCS7 +.Fa "BIO *in" +.Fa "BIO **bcont" +.Fc +.Sh DESCRIPTION +.Fn SMIME_read_PKCS7 +parses a message in S/MIME format. +.Pp +.Fa in +is a +.Vt BIO +to read the message from. +.Pp +If cleartext signing is used, then the content is saved in a memory +.Vt BIO +which is written to +.Pf * Fa bcont , +otherwise +.Pf * Fa bcont +is set to +.Dv NULL . +.Pp +The parsed PKCS#7 structure is returned, or +.Dv NULL +if an error occurred. +.Pp +If +.Pf * Fa bcont +is not +.Dv NULL , +then the message is clear text signed. +.Pf * Fa bcont +can then be passed to +.Xr PKCS7_verify 3 +with the +.Dv PKCS7_DETACHED +flag set. +.Pp +Otherwise the type of the returned structure can be determined using +.Xr PKCS7_type 3 . +.Pp +To support future functionality, if +.Fa bcont +is not +.Dv NULL , +.Pf * Fa bcont +should be initialized to +.Dv NULL . +For example: +.Bd -literal -offset indent +BIO *cont = NULL; +PKCS7 *p7; + +p7 = SMIME_read_PKCS7(in, &cont); +.Ed +.Sh RETURN VALUES +.Fn SMIME_read_PKCS7 +returns a valid +.Vt PKCS7 +structure or +.Dv NULL +if an error occurred. +The error can be obtained from +.Xr ERR_get_error 3 . +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr PKCS7_decrypt 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_type 3 , +.Xr PKCS7_verify 3 , +.Xr SMIME_read_PKCS7 3 +.Sh HISTORY +.Fn SMIME_read_PKCS7 +was added to OpenSSL 0.9.5. +.Sh BUGS +The MIME parser used by +.Fn SMIME_read_PKCS7 +is somewhat primitive. +While it will handle most S/MIME messages, more complex compound +formats may not work. +.Pp +The parser assumes that the +.Vt PKCS7 +structure is always base64 encoded, and it will not handle the case +where it is in binary format or uses quoted printable format. +.Pp +The use of a memory +.Vt BIO +to hold the signed content limits the size of the message which can +be processed due to memory restraints: a streaming single pass +option should be available. diff --git a/lib/libcrypto/man/SMIME_write_PKCS7.3 b/lib/libcrypto/man/SMIME_write_PKCS7.3 new file mode 100644 index 00000000000..f4f465e2e49 --- /dev/null +++ b/lib/libcrypto/man/SMIME_write_PKCS7.3 @@ -0,0 +1,93 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt SMIME_WRITE_PKCS7 3 +.Os +.Sh NAME +.Nm SMIME_write_PKCS7 +.Nd convert PKCS#7 structure to S/MIME format +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft int +.Fo SMIME_write_PKCS7 +.Fa "BIO *out" +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn SMIME_write_PKCS7 +adds the appropriate MIME headers to a PKCS#7 structure to produce an +S/MIME message. +.Pp +.Fa out +is the +.Vt BIO +to write the data to. +.Fa p7 +is the appropriate +.Vt PKCS7 +structure. +If streaming is enabled, then the content must be supplied in the +.Fa data +argument. +.Fa flags +is an optional set of flags. +.Pp +The following flags can be passed in the +.Fa flags +parameter. +.Pp +If +.Dv PKCS7_DETACHED +is set, then cleartext signing will be used. +This option only makes sense for signedData where +.Dv PKCS7_DETACHED +is also set when +.Xr PKCS7_sign 3 +is also called. +.Pp +If the +.Dv PKCS7_TEXT +flag is set, MIME headers for type +.Sy text/plain +are added to the content. +This only makes sense if +.Dv PKCS7_DETACHED +is also set. +.Pp +If the +.Dv PKCS7_STREAM +flag is set, streaming is performed. +This flag should only be set if +.Dv PKCS7_STREAM +was also set in the previous call to +.Xr PKCS7_sign 3 +or +.Xr PKCS7_encrypt 3 . +.Pp +If cleartext signing is being used and +.Dv PKCS7_STREAM +is not set, then the data must be read twice: once to compute the +signature in +.Xr PKCS7_sign 3 +and once to output the S/MIME message. +.Pp +If streaming is performed, the content is output in BER format using +indefinite length constructed encoding except in the case of signed +data with detached content where the content is absent and DER +format is used. +.Sh RETURN VALUES +.Fn SMIME_write_PKCS7 +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr PKCS7_decrypt 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_verify 3 +.Sh HISTORY +.Fn SMIME_write_PKCS7 +was added to OpenSSL 0.9.5. +.Sh BUGS +.Fn SMIME_write_PKCS7 +always base64 encodes PKCS#7 structures. +There should be an option to disable this. diff --git a/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 b/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 new file mode 100644 index 00000000000..755bf3eb86b --- /dev/null +++ b/lib/libcrypto/man/i2d_PKCS7_bio_stream.3 @@ -0,0 +1,44 @@ +.Dd $Mdocdate: November 3 2016 $ +.Dt I2D_PKCS7_BIO_STREAM 3 +.Os +.Sh NAME +.Nm i2d_PKCS7_bio_stream +.Nd output PKCS7 structure in BER format +.Sh SYNOPSIS +.In openssl/pkcs7.h +.Ft int +.Fo i2d_PKCS7_bio_stream +.Fa "BIO *out" +.Fa "PKCS7 *p7" +.Fa "BIO *data" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +.Fn i2d_PKCS7_bio_stream +outputs a +.Vt PKCS7 +structure in BER format. +.Pp +It is otherwise identical to the function +.Xr SMIME_write_PKCS7 3 . +.Pp +This function is effectively a version of +.Xr d2i_PKCS7_bio 3 +supporting streaming. +.Sh RETURN VALUES +.Fn i2d_PKCS7_bio_stream +returns 1 for success or 0 for failure. +.Sh SEE ALSO +.Xr ERR_get_error 3 , +.Xr PEM_write_bio_PKCS7_stream 3 , +.Xr PKCS7_decrypt 3 , +.Xr PKCS7_encrypt 3 , +.Xr PKCS7_sign 3 , +.Xr PKCS7_verify 3 , +.Xr SMIME_write_PKCS7 3 +.Sh HISTORY +.Fn i2d_PKCS7_bio_stream +was added to OpenSSL 1.0.0. +.Sh BUGS +The prefix "i2d" is arguably wrong because the function outputs BER +format. |