From 4e1b50e219c175d3a6a70cc6bf3bf65fb91af269 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Wed, 9 Oct 2002 12:06:12 +0000 Subject: [PATCH] More man pages. --- doc/crypto/ASN1_OBJECT_new.pod | 43 +++++++++ doc/crypto/OBJ_nid2obj.pod | 149 +++++++++++++++++++++++++++++++ doc/crypto/PKCS7_decrypt.pod | 53 +++++++++++ doc/crypto/PKCS7_encrypt.pod | 60 +++++++++++++ doc/crypto/PKCS7_sign.pod | 24 ++++- doc/crypto/PKCS7_verify.pod | 5 +- doc/crypto/SMIME_read_PKCS7.pod | 71 +++++++++++++++ doc/crypto/SMIME_write_PKCS7.pod | 59 ++++++++++++ doc/crypto/d2i_ASN1_OBJECT.pod | 29 ++++++ doc/crypto/d2i_X509_ALGOR.pod | 2 +- doc/crypto/d2i_X509_CRL.pod | 2 +- doc/crypto/d2i_X509_REQ.pod | 2 +- doc/crypto/d2i_X509_SIG.pod | 2 +- 13 files changed, 495 insertions(+), 6 deletions(-) create mode 100644 doc/crypto/ASN1_OBJECT_new.pod create mode 100644 doc/crypto/OBJ_nid2obj.pod create mode 100644 doc/crypto/PKCS7_decrypt.pod create mode 100644 doc/crypto/PKCS7_encrypt.pod create mode 100644 doc/crypto/SMIME_read_PKCS7.pod create mode 100644 doc/crypto/SMIME_write_PKCS7.pod create mode 100644 doc/crypto/d2i_ASN1_OBJECT.pod diff --git a/doc/crypto/ASN1_OBJECT_new.pod b/doc/crypto/ASN1_OBJECT_new.pod new file mode 100644 index 0000000000..51679bfcd9 --- /dev/null +++ b/doc/crypto/ASN1_OBJECT_new.pod @@ -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 structure B. + +=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 and sets an error +code that can be obtained by L. +Otherwise it returns a pointer to the newly allocated structure. + +ASN1_OBJECT_free() returns no value. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL. + +=cut diff --git a/doc/crypto/OBJ_nid2obj.pod b/doc/crypto/OBJ_nid2obj.pod new file mode 100644 index 0000000000..50650bdbce --- /dev/null +++ b/doc/crypto/OBJ_nid2obj.pod @@ -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 to +an ASN1_OBJECT structure, its long name and its short name respectively, +or B is an error occurred. + +OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID +for the object B, the long name or the short name respectively +or NID_undef if an error occurred. + +OBJ_txt2nid() returns NID corresponding to text string . B can be +a long name, a short name or the numerical respresentation of an object. + +OBJ_txt2obj() converts the text string B into an ASN1_OBJECT structure. +If B is 0 then long names and short names will be interpreted +as well as numerical forms. If B is 1 only the numerical form +is acceptable. + +OBJ_obj2txt() converts the B B into a textual representation. +The representation is written as a null terminated string to B +at most B bytes are written, truncating the result if necessary. +The total amount of space required is returned. If B 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 is 1 then the numerical +form will always be used. + +OBJ_cmp() compares B to B. If the two are identical 0 is returned. + +OBJ_dup() returns a copy of B. + +OBJ_create() adds a new object to the internal table. B is the +numerical form of the object, B the short name and B 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. + +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: + + ASN1_OBJECT *o; + o = OBJ_nid2obj(NID_commonName); + +Check is an object is B + + 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 to determine the amount of data that should be written. +Instead B must point to a valid buffer and B 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 is an +error occurred. + +OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B +on error. + +OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return +a NID or NID_undef on error. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/PKCS7_decrypt.pod b/doc/crypto/PKCS7_decrypt.pod new file mode 100644 index 0000000000..b0ca067b89 --- /dev/null +++ b/doc/crypto/PKCS7_decrypt.pod @@ -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 is the private key of the recipient, B is the +recipients certificate, B is a BIO to write the content to and +B 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 parameter. + +If the B flag is set MIME headers for type B are deleted +from the content. If the content is not of type B 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, L + +=head1 HISTORY + +PKCS7_decrypt() was added to OpenSSL 0.9.5 + +=cut diff --git a/doc/crypto/PKCS7_encrypt.pod b/doc/crypto/PKCS7_encrypt.pod new file mode 100644 index 0000000000..c2597a2b15 --- /dev/null +++ b/doc/crypto/PKCS7_encrypt.pod @@ -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 +is a list of recipient certificates. B is the content to be encrypted. +B is the symmetric cipher to use. B 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 parameter must support ASN1 encoding of its +parameters. + +The following flags can be passed in the B parameter. + +If the B flag is set MIME headers for type B are prepended +to the data. + +Normally the supplied content is translated into MIME canonical format (as required +by the S/MIME specifications) if B is set no translation occurs. This +option should be used if the supplied data is in binary format otherwise the translation +will corrupt it. If B is set then B 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, L + +=head1 HISTORY + +PKCS7_decrypt() was added to OpenSSL 0.9.5 + +=cut diff --git a/doc/crypto/PKCS7_sign.pod b/doc/crypto/PKCS7_sign.pod index 95c4609d3c..fc7e649b34 100644 --- a/doc/crypto/PKCS7_sign.pod +++ b/doc/crypto/PKCS7_sign.pod @@ -47,6 +47,28 @@ an SMIMECapabilities attribute. If B is set then no authenticatedA will be used. If B 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 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, L =head1 HISTORY -TBA +PKCS7_sign() was added to OpenSSL 0.9.5 =cut diff --git a/doc/crypto/PKCS7_verify.pod b/doc/crypto/PKCS7_verify.pod index f5200a23ec..07c9fdad40 100644 --- a/doc/crypto/PKCS7_verify.pod +++ b/doc/crypto/PKCS7_verify.pod @@ -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 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, L =head1 HISTORY -TBA +PKCS7_verify() was added to OpenSSL 0.9.5 =cut diff --git a/doc/crypto/SMIME_read_PKCS7.pod b/doc/crypto/SMIME_read_PKCS7.pod new file mode 100644 index 0000000000..ffafa37887 --- /dev/null +++ b/doc/crypto/SMIME_read_PKCS7.pod @@ -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 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. + +The parsed PKCS#7 structure is returned or B if an +error occurred. + +=head1 NOTES + +If B<*bcont> is not B then the message is clear text +signed. B<*bcont> can then be passed to PKCS7_verify() with +the B flag set. + +Otherwise the type of the returned structure can be determined +using PKCS7_type(). + +To support future functionality if B is not B +B<*bcont> should be initialized to B. 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 structure or B +is an error occurred. The error can be obtained from ERR_get_error(3). + +=head1 SEE ALSO + +L, L +L, L, +L, L +L + +=head1 HISTORY + +SMIME_read_PKCS7() was added to OpenSSL 0.9.5 + +=cut diff --git a/doc/crypto/SMIME_write_PKCS7.pod b/doc/crypto/SMIME_write_PKCS7.pod new file mode 100644 index 0000000000..8093241ea4 --- /dev/null +++ b/doc/crypto/SMIME_write_PKCS7.pod @@ -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 is the BIO to write the data to. B is the appropriate +B structure. If cleartext signing (B +argument. B is an optional set of flags. + +=head1 NOTES + +The following flags can be passed in the B parameter. + +If B is set then cleartext signing will be used, +this option only makes sense for signedData where B +is also set when PKCS7_sign() is also called. + +If the B flag is set MIME headers for type B +are added to the content, this only makes sense if B +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, L, +L, L +L + +=head1 HISTORY + +SMIME_write_PKCS7() was added to OpenSSL 0.9.5 + +=cut diff --git a/doc/crypto/d2i_ASN1_OBJECT.pod b/doc/crypto/d2i_ASN1_OBJECT.pod new file mode 100644 index 0000000000..45bb18492c --- /dev/null +++ b/doc/crypto/d2i_ASN1_OBJECT.pod @@ -0,0 +1,29 @@ +=pod + +=head1 NAME + +d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions + +=head1 SYNOPSIS + + #include + + 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 manual page. + +=head1 SEE ALSO + +L + +=head1 HISTORY + +TBA + +=cut diff --git a/doc/crypto/d2i_X509_ALGOR.pod b/doc/crypto/d2i_X509_ALGOR.pod index bf55457697..9e5cd92ca7 100644 --- a/doc/crypto/d2i_X509_ALGOR.pod +++ b/doc/crypto/d2i_X509_ALGOR.pod @@ -8,7 +8,7 @@ d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions. #include - 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 diff --git a/doc/crypto/d2i_X509_CRL.pod b/doc/crypto/d2i_X509_CRL.pod index 613bfd4912..06c5b23c09 100644 --- a/doc/crypto/d2i_X509_CRL.pod +++ b/doc/crypto/d2i_X509_CRL.pod @@ -9,7 +9,7 @@ i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions. #include - 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); diff --git a/doc/crypto/d2i_X509_REQ.pod b/doc/crypto/d2i_X509_REQ.pod index 9e2757f394..be4ad68257 100644 --- a/doc/crypto/d2i_X509_REQ.pod +++ b/doc/crypto/d2i_X509_REQ.pod @@ -9,7 +9,7 @@ i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions. #include - 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); diff --git a/doc/crypto/d2i_X509_SIG.pod b/doc/crypto/d2i_X509_SIG.pod index 39b2353bc3..e48fd79a51 100644 --- a/doc/crypto/d2i_X509_SIG.pod +++ b/doc/crypto/d2i_X509_SIG.pod @@ -8,7 +8,7 @@ d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions. #include - 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 -- 2.25.1