More man pages.

This commit is contained in:
Dr. Stephen Henson 2002-10-09 12:06:12 +00:00
parent d7b2342a6a
commit 4e1b50e219
13 changed files with 495 additions and 6 deletions

View file

@ -0,0 +1,43 @@
=pod
=head1 NAME
ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
=head1 SYNOPSIS
ASN1_OBJECT *ASN1_OBJECT_new(void);
void ASN1_OBJECT_free(ASN1_OBJECT *a);
=head1 DESCRIPTION
The ASN1_OBJECT allocation routines, allocate and free an
ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
=head1 NOTES
Although ASN1_OBJECT_new() allocates a new ASN1_OBJECT structure it
is almost never used in applications. The ASN1 object utility functions
such as OBJ_nid2obj() are used instead.
=head1 RETURN VALUES
If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
ASN1_OBJECT_free() returns no value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)>
=head1 HISTORY
ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL.
=cut

149
doc/crypto/OBJ_nid2obj.pod Normal file
View file

@ -0,0 +1,149 @@
=pod
=head1 NAME
OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid,
OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility
functions
=head1 SYNOPSIS
ASN1_OBJECT * OBJ_nid2obj(int n);
const char * OBJ_nid2ln(int n);
const char * OBJ_nid2sn(int n);
int OBJ_obj2nid(const ASN1_OBJECT *o);
int OBJ_ln2nid(const char *ln);
int OBJ_sn2nid(const char *sn);
int OBJ_txt2nid(const char *s);
ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name);
int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b);
ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);
int OBJ_create(const char *oid,const char *sn,const char *ln);
void OBJ_cleanup(void);
=head1 DESCRIPTION
The ASN1 object utility functions process ASN1_OBJECT structures which are
a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
an ASN1_OBJECT structure, its long name and its short name respectively,
or B<NULL> is an error occurred.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
for the object B<o>, the long name <ln> or the short name <sn> respectively
or NID_undef if an error occurred.
OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
a long name, a short name or the numerical respresentation of an object.
OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
If B<no_name> is 0 then long names and short names will be interpreted
as well as numerical forms. If B<no_name> is 1 only the numerical form
is acceptable.
OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.
The representation is written as a null terminated string to B<buf>
at most B<buf_len> bytes are written, truncating the result if necessary.
The total amount of space required is returned. If B<no_name> is 0 then
if the object has a long or short name then that will be used, otherwise
the numerical form will be used. If B<no_name> is 1 then the numerical
form will always be used.
OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
OBJ_dup() returns a copy of B<o>.
OBJ_create() adds a new object to the internal table. B<oid> is the
numerical form of the object, B<sn> the short name and B<ln> the
long name. A new NID is returned for the created object.
OBJ_cleanup() cleans up OpenSSLs internal object table: this should
be called before an application exits if any new objects were added
using OBJ_create().
=head1 NOTES
Objects in OpenSSL can have a short name, a long name and a numerical
identifier (NID) associated with them. A standard set of objects is
represented in an internal table. The appropriate values are defined
in the header file B<objects.h>.
For example the OID for commonName has the following definitions:
#define SN_commonName "CN"
#define LN_commonName "commonName"
#define NID_commonName 13
New objects can be added by calling OBJ_create().
Table objects have certain advantages over other objects: for example
their NIDs can be used in a C language switch statement. They are
also static constant structures which are shared: that is there
is only a single constant structure for each table object.
Objects which are not in the table have the NID value NID_undef.
Objects do not need to be in the internal tables to be processed,
the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical
form of an OID.
=head1 EXAMPLES
Create an object for B<commonName>:
ASN1_OBJECT *o;
o = OBJ_nid2obj(NID_commonName);
Check is an object is B<commonName>
if (OBJ_obj2nid(obj) == NID_commonName)
/* Do something */
Create a new NID and initialize an object from it:
int new_nid;
ASN1_OBJECT *obj;
new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
obj = OBJ_nid2obj(new_nid);
Create a new object directly:
obj = OBJ_txt2obj("1.2.3.4", 1);
=head1 BUGS
OBJ_obj2txt() is awkward and messy to use: it doesn't follow the
convention of other OpenSSL functions where the buffer can be set
to B<NULL> to determine the amount of data that should be written.
Instead B<buf> must point to a valid buffer and B<buf_len> should
be set to a positive value. A buffer length of 80 should be more
than enough to handle any OID encountered in practice.
=head1 RETURN VALUES
OBJ_nid2obj() returns an ASN1_OBJECT structure or B<NULL> is an
error occurred.
OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
on error.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
a NID or NID_undef on error.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
=head1 HISTORY
TBA
=cut

View file

@ -0,0 +1,53 @@
=pod
=head1 NAME
PKCS7_decrypt - decrypt content from a PKCS#7 envelopedData structure
=head1 SYNOPSIS
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

View file

@ -0,0 +1,60 @@
=pod
=head1 NAME
PKCS7_encrypt - create a PKCS#7 envelopedData structure
=head1 SYNOPSIS
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.
EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because
most clients will support it.
Some old "export grade" clients may only support weak encryption using 40 or 64 bit
RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() respectively.
The algorithm passed in the B<cipher> parameter must support ASN1 encoding of its
parameters.
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.
=head1 RETURN VALUES
PKCS7_encrypt() returns either a valid PKCS7 structure or NULL if an error occurred.
The error can be obtained from ERR_get_error(3).
=head1 BUGS
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_decrypt(3)|PKCS7_decrypt(3)>
=head1 HISTORY
PKCS7_decrypt() was added to OpenSSL 0.9.5
=cut

View file

@ -47,6 +47,28 @@ an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedA
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.
=head1 BUGS
PKCS7_sign() is somewhat limited. It does not support multiple signers, some
advanced attributes such as counter signatures are not supported.
The SHA1 digest algorithm is currently always used.
When the signed data is not detached it will be stored in memory within the
B<PKCS7> structure. This effectively limits the size of messages which can be
signed due to memory restraints. There should be a way to sign data without
having to hold it all in memory, this would however require fairly major
revisions of the OpenSSL ASN1 code.
Clear text signing does not store the content in memory but the way PKCS7_sign()
operates means that two passes of the data must typically be made: one to compute
the signatures and a second to output the data along with the signature. There
should be a way to process the data with only a single pass.
=head1 RETURN VALUES
PKCS7_sign() returns either a valid PKCS7 structure or NULL if an error occurred.
@ -58,6 +80,6 @@ L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)>
=head1 HISTORY
TBA
PKCS7_sign() was added to OpenSSL 0.9.5
=cut

View file

@ -102,12 +102,15 @@ 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
TBA
PKCS7_verify() was added to OpenSSL 0.9.5
=cut

View file

@ -0,0 +1,71 @@
=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

View file

@ -0,0 +1,59 @@
=pod
=head1 NAME
SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format.
=head1 SYNOPSIS
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 cleartext signing (B<multipart/signed) is
being used then the signed data 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 cleartext signing is being used then the data must be read twice:
once to compute the signature in PKCS7_sign() and once to output the
S/MIME message.
=head1 BUGS
SMIME_write_PKCS7() always base64 encodes PKCS#7 structures, there
should be an option to disable this.
There should really be a way to produce cleartext signing using only
a single pass of the data.
=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

View file

@ -0,0 +1,29 @@
=pod
=head1 NAME
d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions
=head1 SYNOPSIS
#include <openssl/objects.h>
ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length);
int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp);
=head1 DESCRIPTION
These functions decode and encode an ASN1 OBJECT IDENTIFIER.
Othewise these behave in a similar way to d2i_X509() and i2d_X509()
described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
=head1 SEE ALSO
L<d2i_X509(3)|d2i_X509(3)>
=head1 HISTORY
TBA
=cut

View file

@ -8,7 +8,7 @@ d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions.
#include <openssl/x509.h>
DH *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length);
X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length);
int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp);
=head1 DESCRIPTION

View file

@ -9,7 +9,7 @@ i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions.
#include <openssl/x509.h>
DH *d2i_X509_CRL(X509_CRL **a, unsigned char **pp, long length);
X509_CRL *d2i_X509_CRL(X509_CRL **a, unsigned char **pp, long length);
int i2d_X509_CRL(X509_CRL *a, unsigned char **pp);
X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x);

View file

@ -9,7 +9,7 @@ i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions.
#include <openssl/x509.h>
DH *d2i_X509_REQ(X509_REQ **a, unsigned char **pp, long length);
X509_REQ *d2i_X509_REQ(X509_REQ **a, unsigned char **pp, long length);
int i2d_X509_REQ(X509_REQ *a, unsigned char **pp);
X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x);

View file

@ -8,7 +8,7 @@ d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions.
#include <openssl/x509.h>
DH *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length);
X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length);
int i2d_X509_SIG(X509_SIG *a, unsigned char **pp);
=head1 DESCRIPTION