From e23d00ab37299e14c06d5d2b599a3793e3d0575c Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Fri, 4 Nov 2016 15:29:03 +0000 Subject: convert X509 manuals from pod to mdoc --- .../libcrypto/doc/X509_NAME_ENTRY_get_object.pod | 70 ----- .../libcrypto/doc/X509_NAME_add_entry_by_txt.pod | 117 ------- .../libcrypto/doc/X509_NAME_get_index_by_NID.pod | 102 ------ src/lib/libcrypto/doc/X509_NAME_print_ex.pod | 103 ------ src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod | 323 ------------------- .../doc/X509_STORE_CTX_get_ex_new_index.pod | 43 --- src/lib/libcrypto/doc/X509_STORE_CTX_new.pod | 126 -------- .../libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod | 165 ---------- .../doc/X509_STORE_set_verify_cb_func.pod | 54 ---- .../libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod | 172 ---------- src/lib/libcrypto/doc/X509_new.pod | 38 --- src/lib/libcrypto/doc/X509_verify_cert.pod | 53 ---- src/lib/libcrypto/doc/d2i_X509.pod | 231 -------------- src/lib/libcrypto/doc/d2i_X509_ALGOR.pod | 26 -- src/lib/libcrypto/doc/d2i_X509_CRL.pod | 33 -- src/lib/libcrypto/doc/d2i_X509_NAME.pod | 27 -- src/lib/libcrypto/doc/d2i_X509_REQ.pod | 32 -- src/lib/libcrypto/doc/d2i_X509_SIG.pod | 26 -- src/lib/libcrypto/doc/x509.pod | 64 ---- src/lib/libcrypto/man/Makefile | 40 +-- src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3 | 133 ++++++++ src/lib/libcrypto/man/X509_NAME_add_entry_by_txt.3 | 212 +++++++++++++ src/lib/libcrypto/man/X509_NAME_get_index_by_NID.3 | 177 +++++++++++ src/lib/libcrypto/man/X509_NAME_print_ex.3 | 199 ++++++++++++ src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 | 297 ++++++++++++++++++ .../man/X509_STORE_CTX_get_ex_new_index.3 | 54 ++++ src/lib/libcrypto/man/X509_STORE_CTX_new.3 | 229 ++++++++++++++ .../libcrypto/man/X509_STORE_CTX_set_verify_cb.3 | 185 +++++++++++ .../libcrypto/man/X509_STORE_set_verify_cb_func.3 | 54 ++++ .../libcrypto/man/X509_VERIFY_PARAM_set_flags.3 | 271 ++++++++++++++++ src/lib/libcrypto/man/X509_new.3 | 49 +++ src/lib/libcrypto/man/X509_verify_cert.3 | 54 ++++ src/lib/libcrypto/man/d2i_X509.3 | 346 +++++++++++++++++++++ src/lib/libcrypto/man/d2i_X509_ALGOR.3 | 33 ++ src/lib/libcrypto/man/d2i_X509_CRL.3 | 54 ++++ src/lib/libcrypto/man/d2i_X509_NAME.3 | 34 ++ src/lib/libcrypto/man/d2i_X509_REQ.3 | 53 ++++ src/lib/libcrypto/man/d2i_X509_SIG.3 | 33 ++ src/lib/libcrypto/man/x509.3 | 79 +++++ 39 files changed, 2566 insertions(+), 1825 deletions(-) delete mode 100644 src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod delete mode 100644 src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod delete mode 100644 src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod delete mode 100644 src/lib/libcrypto/doc/X509_NAME_print_ex.pod delete mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod delete mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod delete mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_new.pod delete mode 100644 src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod delete mode 100644 src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod delete mode 100644 src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod delete mode 100644 src/lib/libcrypto/doc/X509_new.pod delete mode 100644 src/lib/libcrypto/doc/X509_verify_cert.pod delete mode 100644 src/lib/libcrypto/doc/d2i_X509.pod delete mode 100644 src/lib/libcrypto/doc/d2i_X509_ALGOR.pod delete mode 100644 src/lib/libcrypto/doc/d2i_X509_CRL.pod delete mode 100644 src/lib/libcrypto/doc/d2i_X509_NAME.pod delete mode 100644 src/lib/libcrypto/doc/d2i_X509_REQ.pod delete mode 100644 src/lib/libcrypto/doc/d2i_X509_SIG.pod delete mode 100644 src/lib/libcrypto/doc/x509.pod create mode 100644 src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3 create mode 100644 src/lib/libcrypto/man/X509_NAME_add_entry_by_txt.3 create mode 100644 src/lib/libcrypto/man/X509_NAME_get_index_by_NID.3 create mode 100644 src/lib/libcrypto/man/X509_NAME_print_ex.3 create mode 100644 src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 create mode 100644 src/lib/libcrypto/man/X509_STORE_CTX_get_ex_new_index.3 create mode 100644 src/lib/libcrypto/man/X509_STORE_CTX_new.3 create mode 100644 src/lib/libcrypto/man/X509_STORE_CTX_set_verify_cb.3 create mode 100644 src/lib/libcrypto/man/X509_STORE_set_verify_cb_func.3 create mode 100644 src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 create mode 100644 src/lib/libcrypto/man/X509_new.3 create mode 100644 src/lib/libcrypto/man/X509_verify_cert.3 create mode 100644 src/lib/libcrypto/man/d2i_X509.3 create mode 100644 src/lib/libcrypto/man/d2i_X509_ALGOR.3 create mode 100644 src/lib/libcrypto/man/d2i_X509_CRL.3 create mode 100644 src/lib/libcrypto/man/d2i_X509_NAME.3 create mode 100644 src/lib/libcrypto/man/d2i_X509_REQ.3 create mode 100644 src/lib/libcrypto/man/d2i_X509_SIG.3 create mode 100644 src/lib/libcrypto/man/x509.3 (limited to 'src/lib') diff --git a/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod b/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod deleted file mode 100644 index 4603202db8..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_ENTRY_get_object.pod +++ /dev/null @@ -1,70 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_ENTRY_get_object, X509_NAME_ENTRY_get_data, -X509_NAME_ENTRY_set_object, X509_NAME_ENTRY_set_data, -X509_NAME_ENTRY_create_by_txt, X509_NAME_ENTRY_create_by_NID, -X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions - -=head1 SYNOPSIS - - #include - - ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne); - ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne); - - int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, ASN1_OBJECT *obj); - int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len); - - X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len); - X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type,unsigned char *bytes, int len); - X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len); - -=head1 DESCRIPTION - -X509_NAME_ENTRY_get_object() retrieves the field name of B in -and B structure. - -X509_NAME_ENTRY_get_data() retrieves the field value of B in -and B structure. - -X509_NAME_ENTRY_set_object() sets the field name of B to B. - -X509_NAME_ENTRY_set_data() sets the field value of B to string type -B and value determined by B and B. - -X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID() -and X509_NAME_ENTRY_create_by_OBJ() create and return an -B structure. - -=head1 NOTES - -X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be -used to examine an B function as returned by -X509_NAME_get_entry() for example. - -X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(), -and X509_NAME_ENTRY_create_by_OBJ() create and return an - -X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(), -X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data() -are seldom used in practice because B structures -are almost always part of B structures and the -corresponding B functions are typically used to -create and add new entries in a single operation. - -The arguments of these functions support similar options to the similarly -named ones of the corresponding B functions such as -X509_NAME_add_entry_by_txt(). So for example B can be set to -B but in the case of X509_set_data() the field name must be -set first so the relevant field information can be looked up internally. - -=head1 RETURN VALUES - -=head1 SEE ALSO - -L, L, -L - -=cut diff --git a/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod b/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod deleted file mode 100644 index f97e05e683..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_add_entry_by_txt.pod +++ /dev/null @@ -1,117 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, -X509_NAME_add_entry_by_NID, X509_NAME_add_entry, X509_NAME_delete_entry - -X509_NAME modification functions - -=head1 SYNOPSIS - - #include - - int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set); - - int X509_NAME_add_entry_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set); - - int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set); - - int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set); - - X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); - -=head1 DESCRIPTION - -X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and -X509_NAME_add_entry_by_NID() add a field whose name is defined -by a string B, an object B or a NID B respectively. -The field value to be added is in B of length B. If -B is -1 then the field length is calculated internally using -strlen(bytes). - -The type of field is determined by B which can either be a -definition of the type of B (such as B) or a -standard ASN1 type (such as B). The new entry is -added to a position determined by B and B. - -X509_NAME_add_entry() adds a copy of B structure B -to B. The new entry is added to a position determined by B -and B. Since a copy of B is added B must be freed up after -the call. - -X509_NAME_delete_entry() deletes an entry from B at position -B. The deleted entry is returned and must be freed up. - -=head1 NOTES - -The use of string types such as B or B -is strongly recommended for the B parameter. This allows the -internal code to correctly determine the type of the field and to -apply length checks according to the relevant standards. This is -done using ASN1_STRING_set_by_NID(). - -If instead an ASN1 type is used no checks are performed and the -supplied data in B is used directly. - -In X509_NAME_add_entry_by_txt() the B string represents -the field name using OBJ_txt2obj(field, 0). - -The B and B parameters determine where a new entry should -be added. For almost all applications B can be set to -1 and B -to 0. This adds a new entry to the end of B as a single valued -RelativeDistinguishedName (RDN). - -B actually determines the index where the new entry is inserted: -if it is -1 it is appended. - -B determines how the new type is added. If it is zero a -new RDN is created. - -If B is -1 or 1 it is added to the previous or next RDN -structure respectively. This will then be a multivalued RDN: -since multivalues RDNs are very seldom used B is almost -always set to zero. - -=head1 EXAMPLES - -Create an B structure: - -"C=UK, O=Disorganized Organization, CN=Joe Bloggs" - - X509_NAME *nm; - nm = X509_NAME_new(); - if (nm == NULL) - /* Some error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "C", "UK", -1, -1, 0)) - /* Error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "O", "Disorganized Organization", -1, -1, 0)) - /* Error */ - if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, - "CN", "Joe Bloggs", -1, -1, 0)) - /* Error */ - -=head1 RETURN VALUES - -X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), -X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for -success of 0 if an error occurred. - -X509_NAME_delete_entry() returns either the deleted B -structure of B if an error occurred. - -=head1 BUGS - -B can still be set to B to use a -different algorithm to determine field types. Since this form does -not understand multicharacter types, performs no length checks and -can result in invalid field types its use is strongly discouraged. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -=cut diff --git a/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod b/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod deleted file mode 100644 index 48510890e8..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_get_index_by_NID.pod +++ /dev/null @@ -1,102 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry, -X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ - -X509_NAME lookup and enumeration functions - -=head1 SYNOPSIS - - #include - - int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos); - int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos); - - int X509_NAME_entry_count(X509_NAME *name); - X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc); - - int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len); - int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len); - -=head1 DESCRIPTION - -These functions allow an B structure to be examined. The -B structure is the same as the B type defined in -RFC2459 (and elsewhere) and used for example in certificate subject -and issuer names. - -X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve -the next index matching B or B after B. B -should initially be set to -1. If there are no more entries -1 is returned. - -X509_NAME_entry_count() returns the total number of entries in B. - -X509_NAME_get_entry() retrieves the B from B -corresponding to index B. Acceptable values for B run from -0 to (X509_NAME_entry_count(name) - 1). The value returned is an -internal pointer which must not be freed. - -X509_NAME_get_text_by_NID(), X509_NAME_get_text_by_OBJ() retrieve -the "text" from the first entry in B which matches B or -B, if no such entry exists -1 is returned. At most B bytes -will be written and the text written to B will be null -terminated. The length of the output string written is returned -excluding the terminating null. If B is then the amount -of space needed in B (excluding the final null) is returned. - -=head1 NOTES - -X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are -legacy functions which have various limitations which make them -of minimal use in practice. They can only find the first matching -entry and will copy the contents of the field verbatim: this can -be highly confusing if the target is a multicharacter string type -like a BMPString or a UTF8String. - -For a more general solution X509_NAME_get_index_by_NID() or -X509_NAME_get_index_by_OBJ() should be used followed by -X509_NAME_get_entry() on any matching indices and then the -various B utility functions on the result. - -=head1 EXAMPLES - -Process all entries: - - int i; - X509_NAME_ENTRY *e; - - for (i = 0; i < X509_NAME_entry_count(nm); i++) { - e = X509_NAME_get_entry(nm, i); - /* Do something with e */ - } - -Process all commonName entries: - - int loc; - X509_NAME_ENTRY *e; - - loc = -1; - for (;;) { - lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); - if (lastpos == -1) - break; - e = X509_NAME_get_entry(nm, lastpos); - /* Do something with e */ - } - -=head1 RETURN VALUES - -X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() -return the index of the next matching entry or -1 if not found. - -X509_NAME_entry_count() returns the total number of entries. - -X509_NAME_get_entry() returns an B pointer to the -requested entry or B if the index is invalid. - -=head1 SEE ALSO - -L, L - -=cut diff --git a/src/lib/libcrypto/doc/X509_NAME_print_ex.pod b/src/lib/libcrypto/doc/X509_NAME_print_ex.pod deleted file mode 100644 index 5cdf636c16..0000000000 --- a/src/lib/libcrypto/doc/X509_NAME_print_ex.pod +++ /dev/null @@ -1,103 +0,0 @@ -=pod - -=head1 NAME - -X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, -X509_NAME_oneline - X509_NAME printing routines. - -=head1 SYNOPSIS - - #include - - int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags); - int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags); - char * X509_NAME_oneline(X509_NAME *a,char *buf,int size); - int X509_NAME_print(BIO *bp, X509_NAME *name, int obase); - -=head1 DESCRIPTION - -X509_NAME_print_ex() prints a human readable version of B to BIO B. -Each line (for multiline formats) is indented by B spaces. The output -format can be extensively customised by use of the B parameter. - -X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output -is written to FILE pointer B. - -X509_NAME_oneline() prints an ASCII version of B to B. At most B -bytes will be written. If B is B then a buffer is dynamically -allocated and returned, otherwise B is returned. - -X509_NAME_print() prints out B to B indenting each line by B -characters. Multiple lines are used if the output (including indent) exceeds -80 characters. - -=head1 NOTES - -The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions -which produce a non standard output form, they don't handle multi character -fields and have various quirks and inconsistencies. Their use is strongly -discouraged in new applications. - -Although there are a large number of possible flags for most purposes -B, B or B will suffice. -As noted on the L manual page -for UTF8 terminals the B should be unset: so for example -B would be used. - -The complete set of the flags supported by X509_NAME_print_ex() is listed below. - -Several options can be ored together. - -The options B, B, -B and B determine the field -separators to use. Two distinct separators are used between distinct -RelativeDistinguishedName components and separate values in the same RDN for a -multi-valued RDN. Multi-valued RDNs are currently very rare so the second -separator will hardly ever be used. - -B uses comma and plus as separators. -B uses comma and plus with spaces: this is more readable -that plain comma and plus. B uses spaced semicolon and -plus. B uses spaced newline and plus respectively. - -If B is set the whole DN is printed in reversed order. - -The fields B, B, B, -B determine how a field name is displayed. It will -use the short name (e.g. CN) the long name (e.g. commonName) always -use OID numerical form (normally OIDs are only used if the field name is not -recognised) and no field name respectively. - -If B is set then spaces will be placed around the '=' character -separating field names and values. - -If B is set then the encoding of unknown fields is -printed instead of the values. - -If B is set then field names are padded to 20 characters: this -is only of use for multiline format. - -Additionally all the options supported by ASN1_STRING_print_ex() can be used to -control how each field value is displayed. - -In addition a number options can be set for commonly used formats. - -B sets options which produce an output compatible with RFC2253 it -is equivalent to: - B - - -B is a more readable one line format which is the same as: - B - -B is a multiline format which is the same as: - B - -B uses a format identical to X509_NAME_print(): in fact it -calls X509_NAME_print() internally. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod deleted file mode 100644 index 270b265ce5..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_get_error.pod +++ /dev/null @@ -1,323 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, -X509_STORE_CTX_get_error_depth, X509_STORE_CTX_get_current_cert, -X509_STORE_CTX_get1_chain, X509_verify_cert_error_string - get or set -certificate verification status information - -=head1 SYNOPSIS - - #include - #include - - int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); - void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s); - int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); - X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); - - STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); - - const char *X509_verify_cert_error_string(long n); - -=head1 DESCRIPTION - -These functions are typically called after X509_verify_cert() has indicated -an error or in a verification callback to determine the nature of an error. - -X509_STORE_CTX_get_error() returns the error code of B, see -the B section for a full description of all error codes. - -X509_STORE_CTX_set_error() sets the error code of B to B. For example -it might be used in a verification callback to set an error based on additional -checks. - -X509_STORE_CTX_get_error_depth() returns the B of the error. This is a -non-negative integer representing where in the certificate chain the error -occurred. If it is zero it occurred in the end entity certificate, one if -it is the certificate which signed the end entity certificate and so on. - -X509_STORE_CTX_get_current_cert() returns the certificate in B which -caused the error or B if no certificate is relevant. - -X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous -call to X509_verify_cert() is successful. If the call to X509_verify_cert() -is B successful the returned chain may be incomplete or invalid. The -returned chain persists after the B structure is freed, when it is -no longer needed it should be free up using: - - sk_X509_pop_free(chain, X509_free); - -X509_verify_cert_error_string() returns a human readable error string for -verification error B. - -=head1 RETURN VALUES - -X509_STORE_CTX_get_error() returns B or an error code. - -X509_STORE_CTX_get_error_depth() returns a non-negative error depth. - -X509_STORE_CTX_get_current_cert() returns the certificate which caused the -error or B if no certificate is relevant to the error. - -X509_verify_cert_error_string() returns a human readable error string for -verification error B. - -=head1 ERROR CODES - -A list of error codes and messages is shown below. Some of the -error codes are defined but currently never returned: these are described as -"unused". - -=over 4 - -=item B - -the operation was successful. - -=item B - -the issuer certificate could not be found: this occurs if the issuer certificate -of an untrusted certificate cannot be found. - -=item B - -the CRL of a certificate could not be found. - -=item B - -the certificate signature could not be decrypted. This means that the actual -signature value could not be determined rather than it not matching the -expected value, this is only meaningful for RSA keys. - -=item B - -the CRL signature could not be decrypted: this means that the actual signature -value could not be determined rather than it not matching the expected value. -Unused. - -=item B - -the public key in the certificate SubjectPublicKeyInfo could not be read. - -=item B - -the signature of the certificate is invalid. - -=item B - -the signature of the certificate is invalid. - -=item B - -the certificate is not yet valid: the notBefore date is after the current time. - -=item B - -the certificate has expired: that is the notAfter date is before the current -time. - -=item B - -the CRL is not yet valid. - -=item B - -the CRL has expired. - -=item B - -the certificate notBefore field contains an invalid time. - -=item B - -the certificate notAfter field contains an invalid time. - -=item B - -the CRL lastUpdate field contains an invalid time. - -=item B - -the CRL nextUpdate field contains an invalid time. - -=item B - -an error occurred trying to allocate memory. This should never happen. - -=item B - -the passed certificate is self signed and the same certificate cannot be found -in the list of trusted certificates. - -=item B - -the certificate chain could be built up using the untrusted certificates but -the root could not be found locally. - -=item B - -the issuer certificate of a locally looked up certificate could not be found. -This normally means the list of trusted certificates is not complete. - -=item B - -no signatures could be verified because the chain contains only one certificate -and it is not self signed. - -=item B - -the certificate chain length is greater than the supplied maximum depth. Unused. - -=item B - -the certificate has been revoked. - -=item B - -a CA certificate is invalid. Either it is not a CA or its extensions are not -consistent with the supplied purpose. - -=item B - -the basicConstraints pathlength parameter has been exceeded. - -=item B - -the supplied certificate cannot be used for the specified purpose. - -=item B - -the root CA is not marked as trusted for the specified purpose. - -=item B - -the root CA is marked to reject the specified purpose. - -=item B - -the current candidate issuer certificate was rejected because its subject name -did not match the issuer name of the current certificate. This is only set -if issuer check debugging is enabled it is used for status notification and -is B in itself an error. - -=item B - -the current candidate issuer certificate was rejected because its subject key -identifier was present and did not match the authority key identifier current -certificate. This is only set if issuer check debugging is enabled it is used -for status notification and is B in itself an error. - -=item B - -the current candidate issuer certificate was rejected because its issuer name -and serial number was present and did not match the authority key identifier of -the current certificate. This is only set if issuer check debugging is enabled -it is used for status notification and is B in itself an error. - -=item B - -the current candidate issuer certificate was rejected because its keyUsage -extension does not permit certificate signing. This is only set if issuer check -debugging is enabled it is used for status notification and is B in itself -an error. - -=item B - -A certificate extension had an invalid value (for example an incorrect -encoding) or some value inconsistent with other extensions. - - -=item B - -A certificate policies extension had an invalid value (for example an incorrect -encoding) or some value inconsistent with other extensions. This error only -occurs if policy processing is enabled. - -=item B - -The verification flags were set to require and explicit policy but none was -present. - -=item B - -The only CRLs that could be found did not match the scope of the certificate. - -=item B - -Some feature of a certificate extension is not supported. Unused. - -=item B - -A name constraint violation occurred in the permitted subtrees. - -=item B - -A name constraint violation occurred in the excluded subtrees. - -=item B - -A certificate name constraints extension included a minimum or maximum field: -this is not supported. - -=item B - -An unsupported name constraint type was encountered. OpenSSL currently only -supports directory name, DNS name, email and URI types. - -=item B - -The format of the name constraint is not recognised: for example an email -address format of a form not mentioned in RFC3280. This could be caused by -a garbage extension or some new feature not currently supported. - -=item B - -An error occurred when attempting to verify the CRL path. This error can only -happen if extended CRL checking is enabled. - -=item B - -an application specific error. This will never be returned unless explicitly -set by an application. - -=back - -=head1 NOTES - -The above functions should be used instead of directly referencing the fields -in the B structure. - -In versions of OpenSSL before 1.0 the current certificate returned by -X509_STORE_CTX_get_current_cert() was never B. Applications should -check the return value before printing out any debugging information relating -to the current certificate. - -If an unrecognised error code is passed to X509_verify_cert_error_string() the -numerical value of the unknown code is returned in a static buffer. This is not -thread safe but will never happen unless an invalid code is passed. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod deleted file mode 100644 index 25224cef1b..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_get_ex_new_index.pod +++ /dev/null @@ -1,43 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, -X509_STORE_CTX_get_ex_data - add application specific data to X509_STORE_CTX -structures - -=head1 SYNOPSIS - - #include - - int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); - - void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in X509_STORE_CTX structures. -Their usage is identical to that of RSA_get_ex_new_index(), RSA_set_ex_data() -and RSA_get_ex_data() as described in L. - -=head1 NOTES - -This mechanism is used internally by the B library to store the B -structure associated with a verification operation in an B -structure. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -X509_STORE_CTX_get_ex_new_index(), X509_STORE_CTX_set_ex_data() and -X509_STORE_CTX_get_ex_data() are available since OpenSSL 0.9.5. - -=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod deleted file mode 100644 index 66c0da04d2..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_new.pod +++ /dev/null @@ -1,126 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, -X509_STORE_CTX_init, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, -X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_param, -X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default - X509_STORE_CTX -initialisation - -=head1 SYNOPSIS - - #include - - X509_STORE_CTX *X509_STORE_CTX_new(void); - void X509_STORE_CTX_cleanup(X509_STORE_CTX *ctx); - void X509_STORE_CTX_free(X509_STORE_CTX *ctx); - - int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, - X509 *x509, STACK_OF(X509) *chain); - - void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); - - void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x); - void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk); - void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); - - X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx); - void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); - int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); - -=head1 DESCRIPTION - -These functions initialise an B structure for subsequent use -by X509_verify_cert(). - -X509_STORE_CTX_new() returns a newly initialised B structure. - -X509_STORE_CTX_cleanup() internally cleans up an B structure. -The context can then be reused with an new call to X509_STORE_CTX_init(). - -X509_STORE_CTX_free() completely frees up B. After this call B -is no longer valid. - -X509_STORE_CTX_init() sets up B for a subsequent verification operation. -The trusted certificate store is set to B, the end entity certificate -to be verified is set to B and a set of additional certificates (which -will be untrusted but may be used to build the chain) in B. Any or -all of the B, B and B parameters can be B. - -X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B -to B. This is an alternative way of specifying trusted certificates -instead of using an B. - -X509_STORE_CTX_set_cert() sets the certificate to be verified in B to -B. - -X509_STORE_CTX_set_chain() sets the additional certificate chain used by B -to B. - -X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate -verification to B. These CRLs will only be used if CRL verification is -enabled in the associated B structure. This might be -used where additional "useful" CRLs are supplied as part of a protocol, -for example in a PKCS#7 structure. - -X509_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an internal pointer -to the verification parameters associated with B. - -X509_STORE_CTX_set0_param() sets the internal verification parameter pointer -to B. After this call B should not be used. - -X509_STORE_CTX_set_default() looks up and sets the default verification -method to B. This uses the function X509_VERIFY_PARAM_lookup() to -find an appropriate set of parameters from B. - -=head1 NOTES - -The certificates and CRLs in a store are used internally and should B -be freed up until after the associated B is freed. Legacy -applications might implicitly use an B like this: - - X509_STORE_CTX ctx; - X509_STORE_CTX_init(&ctx, store, cert, chain); - -this is B recommended in new applications they should instead do: - - X509_STORE_CTX *ctx; - ctx = X509_STORE_CTX_new(); - if (ctx == NULL) - /* Bad error */ - X509_STORE_CTX_init(ctx, store, cert, chain); - -=head1 BUGS - -The certificates and CRLs in a context are used internally and should B -be freed up until after the associated B is freed. Copies -should be made or reference counts increased instead. - -=head1 RETURN VALUES - -X509_STORE_CTX_new() returns an newly allocates context or B is an -error occurred. - -X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred. - -X509_STORE_CTX_get0_param() returns a pointer to an B -structure or B if an error occurred. - -X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), X509_STORE_CTX_trusted_stack(), -X509_STORE_CTX_set_cert(), X509_STORE_CTX_set_chain(), -X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return -values. - -X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. - -=head1 SEE ALSO - -L -L - -=head1 HISTORY - -X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 - -=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod b/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod deleted file mode 100644 index 7dfe430c4c..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_CTX_set_verify_cb.pod +++ /dev/null @@ -1,165 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_set_verify_cb - set verification callback - -=head1 SYNOPSIS - - #include - - void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); - -=head1 DESCRIPTION - -X509_STORE_CTX_set_verify_cb() sets the verification callback of B to -B overwriting any existing callback. - -The verification callback can be used to customise the operation of certificate -verification, either by overriding error conditions or logging errors for -debugging purposes. - -However a verification callback is B essential and the default operation -is often sufficient. - -The B parameter to the callback indicates the value the callback should -return to retain the default behaviour. If it is zero then and error condition -is indicated. If it is 1 then no error occurred. If the flag -B is set then B is set to 2 to indicate the -policy checking is complete. - -The B parameter to the callback is the B structure that -is performing the verification operation. A callback can examine this -structure and receive additional information about the error, for example -by calling X509_STORE_CTX_get_current_cert(). Additional application data can -be passed to the callback via the B mechanism. - -=head1 WARNING - -In general a verification callback should B unconditionally return 1 in -all circumstances because this will allow verification to succeed no matter -what the error. This effectively removes all security from the application -because B certificate (including untrusted generated ones) will be -accepted. - -=head1 NOTES - -The verification callback can be set and inherited from the parent structure -performing the operation. In some cases (such as S/MIME verification) the -B structure is created and destroyed internally and the -only way to set a custom verification callback is by inheriting it from the -associated B. - -=head1 RETURN VALUES - -X509_STORE_CTX_set_verify_cb() does not return a value. - -=head1 EXAMPLES - -Default callback operation: - - int - verify_callback(int ok, X509_STORE_CTX *ctx) - { - return ok; - } - -Simple example, suppose a certificate in the chain is expired and we wish -to continue after this error: - - int - verify_callback(int ok, X509_STORE_CTX *ctx) - { - /* Tolerate certificate expiration */ - if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) - return 1; - /* Otherwise don't override */ - return ok; - } - -More complex example, we don't wish to continue after B certificate has -expired just one specific case: - - int - verify_callback(int ok, X509_STORE_CTX *ctx) - { - int err = X509_STORE_CTX_get_error(ctx); - X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); - - if (err == X509_V_ERR_CERT_HAS_EXPIRED) { - if (check_is_acceptable_expired_cert(err_cert) - return 1; - } - return ok; - } - -Full featured logging callback. In this case the B is assumed to be -a global logging B, an alternative would to store a BIO in B using -B. - - int - verify_callback(int ok, X509_STORE_CTX *ctx) - { - X509 *err_cert; - int err,depth; - - err_cert = X509_STORE_CTX_get_current_cert(ctx); - err = X509_STORE_CTX_get_error(ctx); - depth = X509_STORE_CTX_get_error_depth(ctx); - - BIO_printf(bio_err,"depth=%d ",depth); - if (err_cert) { - X509_NAME_print_ex(bio_err, - X509_get_subject_name(err_cert), 0, - XN_FLAG_ONELINE); - BIO_puts(bio_err, "\n"); - } else - BIO_puts(bio_err, "\n"); - if (!ok) - BIO_printf(bio_err, "verify error:num=%d:%s\n", - err, X509_verify_cert_error_string(err)); - switch (err) { - case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: - BIO_puts(bio_err, "issuer= "); - X509_NAME_print_ex(bio_err, - X509_get_issuer_name(err_cert), 0, - XN_FLAG_ONELINE); - BIO_puts(bio_err, "\n"); - break; - case X509_V_ERR_CERT_NOT_YET_VALID: - case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: - BIO_printf(bio_err, "notBefore="); - ASN1_TIME_print(bio_err, - X509_get_notBefore(err_cert)); - BIO_printf(bio_err, "\n"); - break; - case X509_V_ERR_CERT_HAS_EXPIRED: - case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: - BIO_printf(bio_err, "notAfter="); - ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); - BIO_printf(bio_err, "\n"); - break; - case X509_V_ERR_NO_EXPLICIT_POLICY: - policies_print(bio_err, ctx); - break; - } - if (err == X509_V_OK && ok == 2) - /* print out policies */ - - BIO_printf(bio_err,"verify return:%d\n",ok); - return(ok); - } - -=head1 SEE ALSO - -L -L -L - -=head1 HISTORY - -X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and -OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod b/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod deleted file mode 100644 index 754512341c..0000000000 --- a/src/lib/libcrypto/doc/X509_STORE_set_verify_cb_func.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb - set verification -callback - -=head1 SYNOPSIS - - #include - - void X509_STORE_set_verify_cb(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); - - void X509_STORE_set_verify_cb_func(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); - -=head1 DESCRIPTION - -X509_STORE_set_verify_cb() sets the verification callback of B to -B overwriting any existing callback. - -X509_STORE_set_verify_cb_func() also sets the verification callback but it -is implemented as a macro. - -=head1 NOTES - -The verification callback from an B is inherited by -the corresponding B structure when it is initialized. This can -be used to set the verification callback when the B is -otherwise inaccessible (for example during S/MIME verification). - -=head1 BUGS - -The macro version of this function was the only one available before -OpenSSL 1.0.0. - -=head1 RETURN VALUES - -X509_STORE_set_verify_cb() and X509_STORE_set_verify_cb_func() do not return -a value. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -X509_STORE_set_verify_cb_func() is available in all versions of SSLeay and -OpenSSL. - -X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. - -=cut diff --git a/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod b/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod deleted file mode 100644 index 6c88aec49e..0000000000 --- a/src/lib/libcrypto/doc/X509_VERIFY_PARAM_set_flags.pod +++ /dev/null @@ -1,172 +0,0 @@ -=pod - -=head1 NAME - -X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, -X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, -X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, -X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, -X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 -verification parameters - -=head1 SYNOPSIS - - #include - - int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); - int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, - unsigned long flags); - unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); - - int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); - int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); - - void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); - - int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, - ASN1_OBJECT *policy); - int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, - STACK_OF(ASN1_OBJECT) *policies); - - void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); - int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); - -=head1 DESCRIPTION - -These functions manipulate the B structure associated with -a certificate verification operation. - -The X509_VERIFY_PARAM_set_flags() function sets the flags in B by oring -it with B. See the B section for a complete -description of values the B parameter can take. - -X509_VERIFY_PARAM_get_flags() returns the flags in B. - -X509_VERIFY_PARAM_clear_flags() clears the flags B in B. - -X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B -to B. This determines the acceptable purpose of the certificate -chain, for example SSL client or SSL server. - -X509_VERIFY_PARAM_set_trust() sets the trust setting in B to -B. - -X509_VERIFY_PARAM_set_time() sets the verification time in B to -B. Normally the current time is used. - -X509_VERIFY_PARAM_add0_policy() enables policy checking (it is disabled -by default) and adds B to the acceptable policy set. - -X509_VERIFY_PARAM_set1_policies() enables policy checking (it is disabled -by default) and sets the acceptable policy set to B. Any existing -policy set is cleared. The B parameter can be B to clear -an existing policy set. - -X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B. -That is the maximum number of untrusted CA certificates that can appear in a -chain. - -=head1 RETURN VALUES - -X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), -X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), -X509_VERIFY_PARAM_add0_policy() and X509_VERIFY_PARAM_set1_policies() return 1 -for success and 0 for failure. - -X509_VERIFY_PARAM_get_flags() returns the current verification flags. - -X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return -values. - -X509_VERIFY_PARAM_get_depth() returns the current verification depth. - -=head1 VERIFICATION FLAGS - -The verification flags consists of zero or more of the following flags -ored together. - -B enables CRL checking for the certificate chain leaf -certificate. An error occurs if a suitable CRL cannot be found. - -B enables CRL checking for the entire certificate -chain. - -B disabled critical extension checking. By default -any unhandled critical extensions in certificates or (if checked) CRLs results -in a fatal error. If this flag is set unhandled critical extensions are -ignored. B setting this option for anything other than debugging -purposes can be a security risk. Finer control over which extensions are -supported can be performed in the verification callback. - -THe B flag disables workarounds for some broken -certificates and makes the verification strictly apply B rules. - -B enables proxy certificate verification. - -B enables certificate policy checking, by default -no policy checking is performed. Additional information is sent to the -verification callback relating to policy checking. - -B, B and -B set the B, B and B flags respectively as defined in -B. Policy checking is automatically enabled if any of these flags -are set. - -If B is set and the policy checking is successful -a special status code is set to the verification callback. This permits it -to examine the valid policy tree and perform additional checks or simply -log it for debugging purposes. - -By default some additional features such as indirect CRLs and CRLs signed by -different keys are disabled. If B is set -they are enabled. - -If B ise set delta CRLs (if present) are used to -determine certificate status. If not set deltas are ignored. - -B enables checking of the root CA self signed -certificate signature. By default this check is disabled because it doesn't -add any additional security but in some cases applications might want to -check the signature anyway. A side effect of not checking the root CA -signature is that disabled or unsupported message digests on the root CA -are not treated as fatal errors. - -The B flag enables debugging of certificate -issuer checks. It is B needed unless you are logging certificate -verification. If this flag is set then additional status codes will be sent -to the verification callback and it B be prepared to handle such cases -without assuming they are hard errors. - -=head1 NOTES - -The above functions should be used to manipulate verification parameters -instead of legacy functions which work in specific structures such as -X509_STORE_CTX_set_flags(). - -=head1 BUGS - -Delta CRL checking is currently primitive. Only a single delta can be used and -(partly due to limitations of B) constructed CRLs are not -maintained. - -If CRLs checking is enable CRLs are expected to be available in the -corresponding B structure. No attempt is made to download -CRLs from the CRL distribution points extension. - -=head1 EXAMPLE - -Enable CRL checking when performing certificate verification during SSL -connections associated with an B structure B: - - X509_VERIFY_PARAM *param; - param = X509_VERIFY_PARAM_new(); - X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); - SSL_CTX_set1_param(ctx, param); - X509_VERIFY_PARAM_free(param); - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/X509_new.pod b/src/lib/libcrypto/doc/X509_new.pod deleted file mode 100644 index a36808b825..0000000000 --- a/src/lib/libcrypto/doc/X509_new.pod +++ /dev/null @@ -1,38 +0,0 @@ -=pod - -=head1 NAME - -X509_new, X509_free - X509 certificate ASN1 allocation functions - -=head1 SYNOPSIS - - #include - - X509 *X509_new(void); - void X509_free(X509 *a); - -=head1 DESCRIPTION - -The X509 ASN1 allocation routines, allocate and free an -X509 structure, which represents an X509 certificate. - -X509_new() allocates and initializes a X509 structure. - -X509_free() frees up the B structure B. -If B is a B pointer, no action occurs. - -=head1 RETURN VALUES - -If the allocation fails, X509_new() returns B and sets an error -code that can be obtained by L. -Otherwise it returns a pointer to the newly allocated structure. - -=head1 SEE ALSO - -L, L - -=head1 HISTORY - -X509_new() and X509_free() are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/X509_verify_cert.pod b/src/lib/libcrypto/doc/X509_verify_cert.pod deleted file mode 100644 index f05edd8333..0000000000 --- a/src/lib/libcrypto/doc/X509_verify_cert.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -X509_verify_cert - discover and verify X509 certificate chain - -=head1 SYNOPSIS - - #include - - int X509_verify_cert(X509_STORE_CTX *ctx); - -=head1 DESCRIPTION - -The X509_verify_cert() function attempts to discover and validate a -certificate chain based on parameters in B. A complete description of -the process is contained in the L manual page. - -=head1 RETURN VALUES - -If a complete chain can be built and validated this function returns 1, -otherwise it return zero, in exceptional circumstances it can also -return a negative code. - -If the function fails additional error information can be obtained by -examining B using, for example X509_STORE_CTX_get_error(). - -=head1 NOTES - -Applications rarely call this function directly but it is used by -OpenSSL internally for certificate validation, in both the S/MIME and -SSL/TLS code. - -The negative return value from X509_verify_cert() can only occur if no -certificate is set in B (due to a programming error) or if a retry -operation is requested during internal lookups (which never happens with -standard lookup methods). It is however recommended that application check -for <= 0 return value on error. - -=head1 BUGS - -This function uses the header B as opposed to most chain verification -functions which use B. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -X509_verify_cert() is available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/d2i_X509.pod b/src/lib/libcrypto/doc/d2i_X509.pod deleted file mode 100644 index fad4e8c35b..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509.pod +++ /dev/null @@ -1,231 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, -i2d_X509_fp - X509 encode and decode functions - -=head1 SYNOPSIS - - #include - - X509 *d2i_X509(X509 **px, const unsigned char **in, int len); - int i2d_X509(X509 *x, unsigned char **out); - - X509 *d2i_X509_bio(BIO *bp, X509 **x); - X509 *d2i_X509_fp(FILE *fp, X509 **x); - - int i2d_X509_bio(BIO *bp, X509 *x); - int i2d_X509_fp(FILE *fp, X509 *x); - -=head1 DESCRIPTION - -The X509 encode and decode routines encode and parse an -B structure, which represents an X509 certificate. - -d2i_X509() attempts to decode B bytes at B<*in>. If -successful a pointer to the B structure is returned. If an error -occurred then B is returned. If B is not B then the -returned structure is written to B<*px>. If B<*px> is not B -then it is assumed that B<*px> contains a valid B -structure and an attempt is made to reuse it. If the call is -successful B<*in> is incremented to the byte following the -parsed data. - -i2d_X509() encodes the structure pointed to by B into DER format. -If B is not B is writes the DER encoded data to the buffer -at B<*out>, and increments it to point after the data just written. -If the return value is negative an error occurred, otherwise it -returns the length of the encoded data. - -For OpenSSL 0.9.7 and later if B<*out> is B memory will be -allocated for a buffer and the encoded data written to it. In this -case B<*out> is not incremented and it points to the start of the -data just written. - -d2i_X509_bio() is similar to d2i_X509() except it attempts -to parse data from BIO B. - -d2i_X509_fp() is similar to d2i_X509() except it attempts -to parse data from FILE pointer B. - -i2d_X509_bio() is similar to i2d_X509() except it writes -the encoding of the structure B to BIO B and it -returns 1 for success and 0 for failure. - -i2d_X509_fp() is similar to i2d_X509() except it writes -the encoding of the structure B to BIO B and it -returns 1 for success and 0 for failure. - -=head1 NOTES - -The letters B and B in for example B stand for -"internal" (that is an internal C structure) and "DER". So that -B converts from internal to DER. - -The functions can also understand B forms. - -The actual X509 structure passed to i2d_X509() must be a valid -populated B structure it can B simply be fed with an -empty structure such as that returned by X509_new(). - -The encoded data is in binary form and may contain embedded zeroes. -Therefore any FILE pointers or BIOs should be opened in binary mode. -Functions such as B will B return the correct length -of the encoded structure. - -The ways that B<*in> and B<*out> are incremented after the operation -can trap the unwary. See the B section for some common -errors. - -The reason for the auto increment behaviour is to reflect a typical -usage of ASN1 functions: after one structure is encoded or decoded -another will processed after it. - -=head1 EXAMPLES - -Allocate and encode the DER encoding of an X509 structure: - - int len; - unsigned char *buf, *p; - - len = i2d_X509(x, NULL); - - buf = malloc(len); - - if (buf == NULL) - /* error */ - - p = buf; - - i2d_X509(x, &p); - -If you are using OpenSSL 0.9.7 or later then this can be -simplified to: - - - int len; - unsigned char *buf; - - buf = NULL; - - len = i2d_X509(x, &buf); - - if (len < 0) - /* error */ - -Attempt to decode a buffer: - - X509 *x; - - unsigned char *buf, *p; - - int len; - - /* Something to setup buf and len */ - - p = buf; - - x = d2i_X509(NULL, &p, len); - - if (x == NULL) - /* Some error */ - -Alternative technique: - - X509 *x; - - unsigned char *buf, *p; - - int len; - - /* Something to setup buf and len */ - - p = buf; - - x = NULL; - - if(!d2i_X509(&x, &p, len)) - /* Some error */ - - -=head1 WARNINGS - -The use of temporary variable is mandatory. A common -mistake is to attempt to use a buffer directly as follows: - - int len; - unsigned char *buf; - - len = i2d_X509(x, NULL); - - buf = malloc(len); - - if (buf == NULL) - /* error */ - - i2d_X509(x, &buf); - - /* Other stuff ... */ - - free(buf); - -This code will result in B apparently containing garbage because -it was incremented after the call to point after the data just written. -Also B will no longer contain the pointer allocated by B -and the subsequent call to B may well crash. - -The auto allocation feature (setting buf to NULL) only works on OpenSSL -0.9.7 and later. Attempts to use it on earlier versions will typically -cause a segmentation violation. - -Another trap to avoid is misuse of the B argument to B: - - X509 *x; - - if (!d2i_X509(&x, &p, len)) - /* Some error */ - -This will probably crash somewhere in B. The reason for this -is that the variable B is uninitialized and an attempt will be made to -interpret its (invalid) value as an B structure, typically causing -a segmentation violation. If B is set to NULL first then this will not -happen. - -=head1 BUGS - -In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when -B<*px> is valid is broken and some parts of the reused structure may -persist if they are not present in the new one. As a result the use -of this "reuse" behaviour is strongly discouraged. - -i2d_X509() will not return an error in many versions of OpenSSL, -if mandatory fields are not initialized due to a programming error -then the encoded structure may contain invalid data or omit the -fields entirely and will not be parsed by d2i_X509(). This may be -fixed in future so code should not assume that i2d_X509() will -always succeed. - -=head1 RETURN VALUES - -d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B structure -or B if an error occurs. The error code that can be obtained by -L. - -i2d_X509() returns the number of bytes successfully encoded or a negative -value if an error occurs. The error code can be obtained by -L. - -i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error -occurs The error code can be obtained by L. - -=head1 SEE ALSO - -L - -=head1 HISTORY - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp -are available in all versions of SSLeay and OpenSSL. - -=cut diff --git a/src/lib/libcrypto/doc/d2i_X509_ALGOR.pod b/src/lib/libcrypto/doc/d2i_X509_ALGOR.pod deleted file mode 100644 index 68011679fd..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_ALGOR.pod +++ /dev/null @@ -1,26 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions. - -=head1 SYNOPSIS - - #include - - 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 - -These functions decode and encode an B structure which is -equivalent to the B structure. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L manual page. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/d2i_X509_CRL.pod b/src/lib/libcrypto/doc/d2i_X509_CRL.pod deleted file mode 100644 index 563e4de8e0..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_CRL.pod +++ /dev/null @@ -1,33 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_X509_CRL_fp, -i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include - - X509_CRL *d2i_X509_CRL(X509_CRL **a, const 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); - X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x); - - int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x); - int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x); - -=head1 DESCRIPTION - -These functions decode and encode an X509 CRL (certificate revocation -list). - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L manual page. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/d2i_X509_NAME.pod b/src/lib/libcrypto/doc/d2i_X509_NAME.pod deleted file mode 100644 index 2219885338..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_NAME.pod +++ /dev/null @@ -1,27 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions - -=head1 SYNOPSIS - - #include - - X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length); - int i2d_X509_NAME(X509_NAME *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an B structure which is the -same as the B type defined in RFC2459 (and elsewhere) and used -for example in certificate subject and issuer names. - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L manual page. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/d2i_X509_REQ.pod b/src/lib/libcrypto/doc/d2i_X509_REQ.pod deleted file mode 100644 index baa8ae391e..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_REQ.pod +++ /dev/null @@ -1,32 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp, -i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include - - X509_REQ *d2i_X509_REQ(X509_REQ **a, const 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); - X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x); - - int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x); - int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x); - -=head1 DESCRIPTION - -These functions decode and encode a PKCS#10 certificate request. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L manual page. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/d2i_X509_SIG.pod b/src/lib/libcrypto/doc/d2i_X509_SIG.pod deleted file mode 100644 index 00d03f5ba1..0000000000 --- a/src/lib/libcrypto/doc/d2i_X509_SIG.pod +++ /dev/null @@ -1,26 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions. - -=head1 SYNOPSIS - - #include - - 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 - -These functions decode and encode an X509_SIG structure which is -equivalent to the B structure defined in PKCS#1 and PKCS#7. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L manual page. - -=head1 SEE ALSO - -L - -=cut diff --git a/src/lib/libcrypto/doc/x509.pod b/src/lib/libcrypto/doc/x509.pod deleted file mode 100644 index f9e58e0e41..0000000000 --- a/src/lib/libcrypto/doc/x509.pod +++ /dev/null @@ -1,64 +0,0 @@ -=pod - -=head1 NAME - -x509 - X.509 certificate handling - -=head1 SYNOPSIS - - #include - -=head1 DESCRIPTION - -A X.509 certificate is a structured grouping of information about -an individual, a device, or anything one can imagine. A X.509 CRL -(certificate revocation list) is a tool to help determine if a -certificate is still valid. The exact definition of those can be -found in the X.509 document from ITU-T, or in RFC3280 from PKIX. -In OpenSSL, the type X509 is used to express such a certificate, and -the type X509_CRL is used to express a CRL. - -A related structure is a certificate request, defined in PKCS#10 from -RSA Security, Inc, also reflected in RFC2896. In OpenSSL, the type -X509_REQ is used to express such a certificate request. - -To handle some complex parts of a certificate, there are the types -X509_NAME (to express a certificate name), X509_ATTRIBUTE (to express -a certificate attributes), X509_EXTENSION (to express a certificate -extension) and a few more. - -Finally, there's the supertype X509_INFO, which can contain a CRL, a -certificate and a corresponding private key. - -BI<...>, BI<...> and BI<...> handle X.509 -certificates, with some exceptions, shown below. - -BI<...>, BI<...> and BI<...> -handle X.509 CRLs. - -BI<...>, BI<...> and BI<...> -handle PKCS#10 certificate requests. - -BI<...> handle certificate names. - -BI<...> handle certificate attributes. - -BI<...> handle certificate extensions. - -=head1 SEE ALSO - -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L, -L - -=cut diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 8bc8ffb6aa..a76a03c78a 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.45 2016/11/04 10:17:17 schwarze Exp $ +# $OpenBSD: Makefile,v 1.46 2016/11/04 15:29:03 schwarze Exp $ .include # for NOMAN @@ -153,49 +153,49 @@ MAN= \ SMIME_read_PKCS7.3 \ SMIME_write_PKCS7.3 \ UI_new.3 \ + X509_NAME_ENTRY_get_object.3 \ + X509_NAME_add_entry_by_txt.3 \ + X509_NAME_get_index_by_NID.3 \ + X509_NAME_print_ex.3 \ + X509_STORE_CTX_get_error.3 \ + X509_STORE_CTX_get_ex_new_index.3 \ + X509_STORE_CTX_new.3 \ + X509_STORE_CTX_set_verify_cb.3 \ + X509_STORE_set_verify_cb_func.3 \ + X509_VERIFY_PARAM_set_flags.3 \ + X509_new.3 \ + X509_verify_cert.3 \ bn_dump.3 \ crypto.3 \ d2i_ASN1_OBJECT.3 \ d2i_PKCS8PrivateKey_bio.3 \ d2i_RSAPublicKey.3 \ + d2i_X509.3 \ + d2i_X509_ALGOR.3 \ + d2i_X509_CRL.3 \ + d2i_X509_NAME.3 \ + d2i_X509_REQ.3 \ + d2i_X509_SIG.3 \ des_read_pw.3 \ evp.3 \ i2d_PKCS7_bio_stream.3 \ lh_new.3 \ rsa.3 \ + x509.3 GENMAN= \ RC4.3 \ RIPEMD160.3 \ SHA1.3 \ - X509_NAME_ENTRY_get_object.3 \ - X509_NAME_add_entry_by_txt.3 \ - X509_NAME_get_index_by_NID.3 \ - X509_NAME_print_ex.3 \ - X509_STORE_CTX_get_error.3 \ - X509_STORE_CTX_get_ex_new_index.3 \ - X509_STORE_CTX_new.3 \ - X509_STORE_CTX_set_verify_cb.3 \ - X509_STORE_set_verify_cb_func.3 \ - X509_VERIFY_PARAM_set_flags.3 \ - X509_new.3 \ - X509_verify_cert.3 \ bn.3 \ d2i_DHparams.3 \ d2i_DSAPublicKey.3 \ d2i_ECPKParameters.3 \ - d2i_X509.3 \ - d2i_X509_ALGOR.3 \ - d2i_X509_CRL.3 \ - d2i_X509_NAME.3 \ - d2i_X509_REQ.3 \ - d2i_X509_SIG.3 \ dh.3 \ dsa.3 \ ec.3 \ engine.3 \ lh_stats.3 \ - x509.3 \ MAN+= ${GENMAN} diff --git a/src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3 b/src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3 new file mode 100644 index 0000000000..97978ea542 --- /dev/null +++ b/src/lib/libcrypto/man/X509_NAME_ENTRY_get_object.3 @@ -0,0 +1,133 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_NAME_ENTRY_GET_OBJECT 3 +.Os +.Sh NAME +.Nm X509_NAME_ENTRY_get_object , +.Nm X509_NAME_ENTRY_get_data , +.Nm X509_NAME_ENTRY_set_object , +.Nm X509_NAME_ENTRY_set_data , +.Nm X509_NAME_ENTRY_create_by_txt , +.Nm X509_NAME_ENTRY_create_by_NID , +.Nm X509_NAME_ENTRY_create_by_OBJ +.Nd X509_NAME_ENTRY utility functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft ASN1_OBJECT * +.Fo X509_NAME_ENTRY_get_object +.Fa "X509_NAME_ENTRY *ne" +.Fc +.Ft ASN1_STRING * +.Fo X509_NAME_ENTRY_get_data +.Fa "X509_NAME_ENTRY *ne" +.Fc +.Ft int +.Fo X509_NAME_ENTRY_set_object +.Fa "X509_NAME_ENTRY *ne" +.Fa "ASN1_OBJECT *obj" +.Fc +.Ft int +.Fo X509_NAME_ENTRY_set_data +.Fa "X509_NAME_ENTRY *ne" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_ENTRY_create_by_txt +.Fa "X509_NAME_ENTRY **ne" +.Fa "const char *field" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_ENTRY_create_by_NID +.Fa "X509_NAME_ENTRY **ne" +.Fa "int nid" +.Fa "int type" +.Fa "unsigned char *bytes" +.Fa "int len" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_ENTRY_create_by_OBJ +.Fa "X509_NAME_ENTRY **ne" +.Fa "ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Sh DESCRIPTION +.Fn X509_NAME_ENTRY_get_object +retrieves the field name of +.Fa ne +in an +.Vt ASN1_OBJECT +structure. +.Pp +.Fn X509_NAME_ENTRY_get_data +retrieves the field value of +.Fa ne +in an +.Vt ASN1_STRING +structure. +.Pp +.Fn X509_NAME_ENTRY_set_object +sets the field name of +.Fa ne +to +.Fa obj . +.Pp +.Fn X509_NAME_ENTRY_set_data +sets the field value of +.Fa ne +to string type +.Fa type +and the value determined by +.Fa bytes +and +.Fa len . +.Pp +.Fn X509_NAME_ENTRY_create_by_txt , +.Fn X509_NAME_ENTRY_create_by_NID , +and +.Fn X509_NAME_ENTRY_create_by_OBJ +create and return an +.Vt X509_NAME_ENTRY +structure. +.Pp +.Fn X509_NAME_ENTRY_get_object +and +.Fn X509_NAME_ENTRY_get_data +can be used to examine an +.Vt X509_NAME_ENTRY +function as returned by +.Xr X509_NAME_get_entry 3 +for example. +.Pp +.Fn X509_NAME_ENTRY_create_by_txt , +.Fn X509_NAME_ENTRY_create_by_OBJ , +.Fn X509_NAME_ENTRY_create_by_NID , +and +.Fn X509_NAME_ENTRY_set_data +are seldom used in practice because +.Vt X509_NAME_ENTRY +structures are almost always part of +.Vt X509_NAME +structures and the corresponding X509_NAME functions are typically +used to create and add new entries in a single operation. +.Pp +The arguments of these functions support similar options to the +similarly named ones of the corresponding X509_NAME functions such as +.Xr X509_NAME_add_entry_by_txt 3 . +So for example +.Fa type +can be set to +.Dv MBSTRING_ASC , +but in the case of +.Fn X509_NAME_ENTRY_set_data +the field name must be set first so the relevant field information +can be looked up internally. +.Sh SEE ALSO +.Xr d2i_X509_NAME 3 , +.Xr ERR_get_error 3 , +.Xr OBJ_nid2obj 3 diff --git a/src/lib/libcrypto/man/X509_NAME_add_entry_by_txt.3 b/src/lib/libcrypto/man/X509_NAME_add_entry_by_txt.3 new file mode 100644 index 0000000000..c77763cc68 --- /dev/null +++ b/src/lib/libcrypto/man/X509_NAME_add_entry_by_txt.3 @@ -0,0 +1,212 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_NAME_ADD_ENTRY_BY_TXT 3 +.Os +.Sh NAME +.Nm X509_NAME_add_entry_by_txt , +.Nm X509_NAME_add_entry_by_OBJ , +.Nm X509_NAME_add_entry_by_NID , +.Nm X509_NAME_add_entry , +.Nm X509_NAME_delete_entry +.Nd X509_NAME modification functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_NAME_add_entry_by_txt +.Fa "X509_NAME *name" +.Fa "const char *field" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft int +.Fo X509_NAME_add_entry_by_OBJ +.Fa "X509_NAME *name" +.Fa "ASN1_OBJECT *obj" +.Fa "int type" +.Fa "unsigned char *bytes" +.Fa "int len" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft int +.Fo X509_NAME_add_entry_by_NID +.Fa "X509_NAME *name" +.Fa "int nid" +.Fa "int type" +.Fa "unsigned char *bytes" +.Fa "int len" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft int +.Fo X509_NAME_add_entry +.Fa "X509_NAME *name" +.Fa "X509_NAME_ENTRY *ne" +.Fa "int loc" +.Fa "int set" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_delete_entry +.Fa "X509_NAME *name" +.Fa "int loc" +.Fc +.Sh DESCRIPTION +.Fn X509_NAME_add_entry_by_txt , +.Fn X509_NAME_add_entry_by_OBJ , +and +.Fn X509_NAME_add_entry_by_NID +add a field whose name is defined by a string +.Fa field , +an object +.Fa obj +or a NID +.Fa nid , +respectively. +The field value to be added is in +.Fa bytes +of length +.Fa len . +If +.Fa len +is -1 then the field length is calculated internally using +.Fn strlen bytes . +.Pp +The type of field is determined by +.Fa type +which can either be a definition of the type of +.Fa bytes +(such as +.Dv MBSTRING_ASC ) +or a standard ASN1 type (such as +.Dv V_ASN1_IA5STRING ) . +The new entry is added to a position determined by +.Fa loc +and +.Fa set . +.Pp +.Fn X509_NAME_add_entry +adds a copy of a +.Vt X509_NAME_ENTRY +structure +.Fa ne +to +.Fa name . +The new entry is added to a position determined by +.Fa loc +and +.Fa set . +Since a copy of +.Fa ne +is added, +.Fa ne +must be freed up after the call. +.Pp +.Fn X509_NAME_delete_entry +deletes an entry from +.Fa name +at position +.Fa loc . +The deleted entry is returned and must be freed up. +.Pp +The use of string types such as +.Dv MBSTRING_ASC +or +.Dv MBSTRING_UTF8 +is strongly recommended for the +.Fa type +parameter. +This allows the internal code to correctly determine the type of the +field and to apply length checks according to the relevant standards. +This is done using +.Xr ASN1_STRING_set_by_NID 3 . +.Pp +If instead an ASN1 type is used, no checks are performed and the supplied +data in +.Fa bytes +is used directly. +.Pp +In +.Fn X509_NAME_add_entry_by_txt +the +.Fa field +string represents the field name using +.Fn OBJ_txt2obj field 0 . +.Pp +The +.Fa loc +and +.Fa set +parameters determine where a new entry should be added. +For almost all applications, +.Fa loc +can be set to -1 and +.Fa set +to 0. +This adds a new entry to the end of +.Fa name +as a single valued RelativeDistinguishedName (RDN). +.Pp +.Fa loc +actually determines the index where the new entry is inserted: +if it is -1 it is appended. +.Pp +.Fa set +determines how the new type is added. +If it is zero a new RDN is created. +.Pp +If +.Fa set +is -1 or 1 it is added to the previous or next RDN structure +respectively. +This will then be a multivalued RDN: since multivalues RDNs are very +seldom used, +.Fa set +is almost always set to zero. +.Sh RETURN VALUES +.Fn X509_NAME_add_entry_by_txt , +.Fn X509_NAME_add_entry_by_OBJ , +.Fn X509_NAME_add_entry_by_NID , +and +.Fn X509_NAME_add_entry +return 1 for success or 0 if an error occurred. +.Pp +.Fn X509_NAME_delete_entry +returns either the deleted +.Vt X509_NAME_ENTRY +structure or +.Dv NULL +if an error occurred. +.Sh EXAMPLES +Create an +.Vt X509_NAME +structure: +.Pp +.D1 C=UK, O=Disorganized Organization, CN=Joe Bloggs +.Bd -literal +X509_NAME *nm; +nm = X509_NAME_new(); +if (nm == NULL) + /* Some error */ +if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, + "C", "UK", -1, -1, 0)) + /* Error */ +if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, + "O", "Disorganized Organization", -1, -1, 0)) + /* Error */ +if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC, + "CN", "Joe Bloggs", -1, -1, 0)) + /* Error */ +.Ed +.Sh SEE ALSO +.Xr d2i_X509_NAME 3 , +.Xr ERR_get_error 3 +.Sh BUGS +.Fa type +can still be set to +.Dv V_ASN1_APP_CHOOSE +to use a different algorithm to determine field types. +Since this form does not understand multicharacter types, performs +no length checks, and can result in invalid field types, its use +is strongly discouraged. diff --git a/src/lib/libcrypto/man/X509_NAME_get_index_by_NID.3 b/src/lib/libcrypto/man/X509_NAME_get_index_by_NID.3 new file mode 100644 index 0000000000..4710fd1ec2 --- /dev/null +++ b/src/lib/libcrypto/man/X509_NAME_get_index_by_NID.3 @@ -0,0 +1,177 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_NAME_GET_INDEX_BY_NID 3 +.Os +.Sh NAME +.Nm X509_NAME_get_index_by_NID , +.Nm X509_NAME_get_index_by_OBJ , +.Nm X509_NAME_get_entry , +.Nm X509_NAME_entry_count , +.Nm X509_NAME_get_text_by_NID , +.Nm X509_NAME_get_text_by_OBJ +.Nd X509_NAME lookup and enumeration functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_NAME_get_index_by_NID +.Fa "X509_NAME *name" +.Fa "int nid" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_NAME_get_index_by_OBJ +.Fa "X509_NAME *name" +.Fa "ASN1_OBJECT *obj" +.Fa "int lastpos" +.Fc +.Ft int +.Fo X509_NAME_entry_count +.Fa "X509_NAME *name" +.Fc +.Ft X509_NAME_ENTRY * +.Fo X509_NAME_get_entry +.Fa "X509_NAME *name" +.Fa "int loc" +.Fc +.Ft int +.Fo X509_NAME_get_text_by_NID +.Fa "X509_NAME *name" +.Fa "int nid" +.Fa "char *buf" +.Fa "int len" +.Fc +.Ft int +.Fo X509_NAME_get_text_by_OBJ +.Fa "X509_NAME *name" +.Fa "ASN1_OBJECT *obj" +.Fa "char *buf" +.Fa "int len" +.Fc +.Sh DESCRIPTION +These functions allow an +.Vt X509_NAME +structure to be examined. +The +.Vt X509_NAME +structure is the same as the +.Sy Name +type defined in RFC2459 (and elsewhere) and used for example in +certificate subject and issuer names. +.Pp +.Fn X509_NAME_get_index_by_NID +and +.Fn X509_NAME_get_index_by_OBJ +retrieve the next index matching +.Fa nid +or +.Fa obj +after +.Fa lastpos . +.Fa lastpos +should initially be set to -1. +If there are no more entries, -1 is returned. +.Pp +.Fn X509_NAME_entry_count +returns the total number of entries in +.Fa name . +.Pp +.Fn X509_NAME_get_entry +retrieves the +.Vt X509_NAME_ENTRY +from +.Fa name +corresponding to index +.Fa loc . +Acceptable values for +.Fa loc +run from 0 to +.Fn X509_NAME_entry_count name +- 1. +The value returned is an internal pointer which must not be freed. +.Pp +.Fn X509_NAME_get_text_by_NID +and +.Fn X509_NAME_get_text_by_OBJ +retrieve the "text" from the first entry in +.Fa name +which matches +.Fa nid +or +.Fa obj . +If no such entry exists, -1 is returned. +At most +.Fa len +bytes will be written and the text written to +.Fa buf +will be NUL terminated. +The length of the output string written is returned excluding the +terminating NUL. +If +.Fa buf +is +.Dv NULL +then the amount of space needed in +.Fa buf +(excluding the final NUL) is returned. +.Sh RETURN VALUES +.Fn X509_NAME_get_index_by_NID +and +.Fn X509_NAME_get_index_by_OBJ +return the index of the next matching entry or -1 if not found. +.Pp +.Fn X509_NAME_entry_count +returns the total number of entries. +.Pp +.Fn X509_NAME_get_entry +returns an +.Vt X509_NAME +pointer to the requested entry or +.Dv NULL +if the index is invalid. +.Sh EXAMPLES +Process all entries: +.Bd -literal +int i; +X509_NAME_ENTRY *e; + +for (i = 0; i < X509_NAME_entry_count(nm); i++) { + e = X509_NAME_get_entry(nm, i); + /* Do something with e */ +} +.Ed +.Pp +Process all commonName entries: +.Bd -literal +int loc; +X509_NAME_ENTRY *e; + +loc = -1; +for (;;) { + lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); + if (lastpos == -1) + break; + e = X509_NAME_get_entry(nm, lastpos); + /* Do something with e */ +} +.Ed +.Sh SEE ALSO +.Xr d2i_X509_NAME 3 , +.Xr ERR_get_error 3 +.Sh CAVEATS +.Fn X509_NAME_get_text_by_NID +and +.Fn X509_NAME_get_text_by_OBJ +are legacy functions which have various limitations which make them of +minimal use in practice. +They can only find the first matching entry and will copy the contents +of the field verbatim: this can be highly confusing if the target is a +multicharacter string type like a BMPString or a UTF8String. +.Pp +For a more general solution, +.Fn X509_NAME_get_index_by_NID +or +.Fn X509_NAME_get_index_by_OBJ +should be used, followed by +.Fn X509_NAME_get_entry +on any matching indices and then the various +.Vt X509_NAME_ENTRY +utility functions on the result. diff --git a/src/lib/libcrypto/man/X509_NAME_print_ex.3 b/src/lib/libcrypto/man/X509_NAME_print_ex.3 new file mode 100644 index 0000000000..ca5fc61e18 --- /dev/null +++ b/src/lib/libcrypto/man/X509_NAME_print_ex.3 @@ -0,0 +1,199 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_NAME_PRINT_EX 3 +.Os +.Sh NAME +.Nm X509_NAME_print_ex , +.Nm X509_NAME_print_ex_fp , +.Nm X509_NAME_print , +.Nm X509_NAME_oneline +.Nd X509_NAME printing routines +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_NAME_print_ex +.Fa "BIO *out" +.Fa "X509_NAME *nm" +.Fa "int indent" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo X509_NAME_print_ex_fp +.Fa "FILE *fp" +.Fa "X509_NAME *nm" +.Fa "int indent" +.Fa "unsigned long flags" +.Fc +.Ft char * +.Fo X509_NAME_oneline +.Fa "X509_NAME *a" +.Fa "char *buf" +.Fa "int size" +.Fc +.Ft int +.Fo X509_NAME_print +.Fa "BIO *bp" +.Fa "X509_NAME *name" +.Fa "int obase" +.Fc +.Sh DESCRIPTION +.Fn X509_NAME_print_ex +prints a human readable version of +.Fa nm +to +.Vt BIO +.Fa out . +Each line (for multiline formats) is indented by +.Fa indent +spaces. +The output format can be extensively customised by use of the +.Fa flags +parameter. +.Pp +.Fn X509_NAME_print_ex_fp +is identical to +.Fn X509_NAME_print_ex +except the output is written to the +.Vt FILE +pointer +.Fa fp . +.Pp +.Fn X509_NAME_oneline +prints an ASCII version of +.Fa a +to +.Fa buf . +At most +.Fa size +bytes will be written. +If +.Fa buf +is +.Dv NULL , +then a buffer is dynamically allocated and returned, otherwise +.Fa buf +is returned. +.Pp +.Fn X509_NAME_print +prints out +.Fa name +to +.Fa bp +indenting each line by +.Fa obase +characters. +Multiple lines are used if the output (including indent) exceeds 80 +characters. +.Pp +The functions +.Fn X509_NAME_oneline +and +.Fn X509_NAME_print +are legacy functions which produce a non standard output form. +They don't handle multi character fields and have various quirks +and inconsistencies. +Their use is strongly discouraged in new applications. +.Pp +Although there are a large number of possible flags, for most purposes +.Dv XN_FLAG_ONELINE , +.Dv XN_FLAG_MULTILINE , +or +.Dv XN_FLAG_RFC2253 +will suffice. +As noted on the +.Xr ASN1_STRING_print_ex 3 +manual page, for UTF-8 terminals the +.Dv ASN1_STRFLGS_ESC_MSB +should be unset: so for example +.Dv XN_FLAG_ONELINE No & Pf ~ Dv ASN1_STRFLGS_ESC_MSB +would be used. +.Pp +The complete set of the flags supported by +.Dv X509_NAME_print_ex +is listed below. +.Pp +Several options can be OR'ed together. +.Pp +The options +.Dv XN_FLAG_SEP_COMMA_PLUS , +.Dv XN_FLAG_SEP_CPLUS_SPC , +.Dv XN_FLAG_SEP_SPLUS_SPC , +and +.Dv XN_FLAG_SEP_MULTILINE +determine the field separators to use. +Two distinct separators are used between distinct +RelativeDistinguishedName components and separate values in the same RDN +for a multi-valued RDN. +Multi-valued RDNs are currently very rare so the second separator +will hardly ever be used. +.Pp +.Dv XN_FLAG_SEP_COMMA_PLUS +uses comma and plus as separators. +.Dv XN_FLAG_SEP_CPLUS_SPC +uses comma and plus with spaces: +this is more readable that plain comma and plus. +.Dv XN_FLAG_SEP_SPLUS_SPC +uses spaced semicolon and plus. +.Dv XN_FLAG_SEP_MULTILINE +uses spaced newline and plus respectively. +.Pp +If +.Dv XN_FLAG_DN_REV +is set, the whole DN is printed in reversed order. +.Pp +The fields +.Dv XN_FLAG_FN_SN , +.Dv XN_FLAG_FN_LN , +.Dv XN_FLAG_FN_OID , +and +.Dv XN_FLAG_FN_NONE +determine how a field name is displayed. +It will use the short name (e.g. CN) the long name (e.g. commonName) +always use OID numerical form (normally OIDs are only used if the +field name is not recognised) and no field name respectively. +.Pp +If +.Dv XN_FLAG_SPC_EQ +is set, then spaces will be placed around the +.Ql = +character separating field names and values. +.Pp +If +.Dv XN_FLAG_DUMP_UNKNOWN_FIELDS +is set, then the encoding of unknown fields is printed instead of the +values. +.Pp +If +.Dv XN_FLAG_FN_ALIGN +is set, then field names are padded to 20 characters: +this is only of use for multiline format. +.Pp +Additionally, all the options supported by +.Xr ASN1_STRING_print_ex 3 +can be used to control how each field value is displayed. +.Pp +In addition a number options can be set for commonly used formats. +.Pp +.Dv XN_FLAG_RFC2253 +sets options which produce an output compatible with RFC2253. +It is equivalent to +.Dv ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | +.Dv XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS . +.Pp +.Dv XN_FLAG_ONELINE +is a more readable one line format which is the same as: +.Dv ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | +.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_SN . +.Pp +.Dv XN_FLAG_MULTILINE +is a multiline format which is the same as: +.Dv ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | +.Dv XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN . +.Pp +.Dv XN_FLAG_COMPAT +uses a format identical to +.Fn X509_NAME_print : +in fact it calls +.Fn X509_NAME_print +internally. +.Sh SEE ALSO +.Xr ASN1_STRING_print_ex 3 diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 b/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 new file mode 100644 index 0000000000..f31e438cde --- /dev/null +++ b/src/lib/libcrypto/man/X509_STORE_CTX_get_error.3 @@ -0,0 +1,297 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_STORE_CTX_GET_ERROR 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_get_error , +.Nm X509_STORE_CTX_set_error , +.Nm X509_STORE_CTX_get_error_depth , +.Nm X509_STORE_CTX_get_current_cert , +.Nm X509_STORE_CTX_get1_chain , +.Nm X509_verify_cert_error_string +.Nd get or set certificate verification status information +.Sh SYNOPSIS +.In openssl/x509.h +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_CTX_get_error +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_error +.Fa "X509_STORE_CTX *ctx" +.Fa "int s" +.Fc +.Ft int +.Fo X509_STORE_CTX_get_error_depth +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft X509 * +.Fo X509_STORE_CTX_get_current_cert +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft STACK_OF(X509) * +.Fo X509_STORE_CTX_get1_chain +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft const char * +.Fo X509_verify_cert_error_string +.Fa "long n" +.Fc +.Sh DESCRIPTION +These functions are typically called after +.Xr X509_verify_cert 3 +has indicated an error or in a verification callback to determine the +nature of an error. +.Pp +.Fn X509_STORE_CTX_get_error +returns the error code of +.Fa ctx . +See the +.Sy ERROR CODES +section for a full description of all error codes. +.Pp +.Fn X509_STORE_CTX_set_error +sets the error code of +.Fa ctx +to +.Fa s . +For example it might be used in a verification callback to set an error +based on additional checks. +.Pp +.Fn X509_STORE_CTX_get_error_depth +returns the depth of the error. +This is a non-negative integer representing where in the certificate +chain the error occurred. +If it is zero, it occurred in the end entity certificate, one if it is +the certificate which signed the end entity certificate, and so on. +.Pp +.Fn X509_STORE_CTX_get_current_cert +returns the certificate in +.Fa ctx +which caused the error or +.Dv NULL +if no certificate is relevant. +.Pp +.Fn X509_STORE_CTX_get1_chain +returns a complete validate chain if a previous call to +.Xr X509_verify_cert 3 +is successful. +If the call to +.Xr X509_verify_cert 3 +is +.Sy not +successful, the returned chain may be incomplete or invalid. +The returned chain persists after the +.Fa ctx +structure is freed. +When it is no longer needed, it should be free up using +.Fn sk_X509_pop_free chain X509_free . +.Pp +.Fn X509_verify_cert_error_string +returns a human readable error string for verification error +.Fa n . +.Pp +The above functions should be used instead of directly referencing the +fields in the +.Sy X509_VERIFY_CTX +structure. +.Pp +In versions of OpenSSL before 1.0, the current certificate returned by +.Fn X509_STORE_CTX_get_current_cert +was never +.Dv NULL . +Applications should check the return value before printing out any +debugging information relating to the current certificate. +.Pp +If an unrecognised error code is passed to +.Fn X509_verify_cert_error_string , +the numerical value of the unknown code is returned in a static buffer. +This is not thread safe but will never happen unless an invalid code is +passed. +.Sh RETURN VALUES +.Fn X509_STORE_CTX_get_error +returns +.Dv X509_V_OK +or an error code. +.Pp +.Fn X509_STORE_CTX_get_error_depth +returns a non-negative error depth. +.Pp +.Fn X509_STORE_CTX_get_current_cert +returns the certificate which caused the error or +.Dv NULL +if no certificate is relevant to the error. +.Pp +.Fn X509_verify_cert_error_string +returns a human readable error string for verification error +.Fa n . +.Sh ERROR CODES +A list of error codes and messages is shown below. +Some of the error codes are defined but currently never returned: +these are described as "unused". +.Bl -tag -width Ds +.It Dv X509_V_OK : No ok +The operation was successful. +.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT : \ + No unable to get issuer certificate +The issuer certificate could not be found: this occurs if the issuer +certificate of an untrusted certificate cannot be found. +.It Dv X509_V_ERR_UNABLE_TO_GET_CRL : No unable to get certificate CRL +The CRL of a certificate could not be found. +.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE : \ + No unable to decrypt certificate's signature +The certificate signature could not be decrypted. +This means that the actual signature value could not be determined +rather than it not matching the expected value, this is only meaningful +for RSA keys. +.It Dv X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE : \ + No unable to decrypt CRL's signature +The CRL signature could not be decrypted: this means that the actual +signature value could not be determined rather than it not matching the +expected value. +Unused. +.It Dv X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY : \ + No unable to decode issuer public key +The public key in the certificate SubjectPublicKeyInfo could not be read. +.It Dv X509_V_ERR_CERT_SIGNATURE_FAILURE : No certificate signature failure +The signature of the certificate is invalid. +.It Dv X509_V_ERR_CRL_SIGNATURE_FAILURE : No CRL signature failure +The signature of the certificate is invalid. +.It Dv X509_V_ERR_CERT_NOT_YET_VALID : No certificate is not yet valid +The certificate is not yet valid: the notBefore date is after the +current time. +.It Dv X509_V_ERR_CERT_HAS_EXPIRED : No certificate has expired +The certificate has expired: that is the notAfter date is before the +current time. +.It Dv X509_V_ERR_CRL_NOT_YET_VALID : No CRL is not yet valid +The CRL is not yet valid. +.It Dv X509_V_ERR_CRL_HAS_EXPIRED : No CRL has expired +The CRL has expired. +.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD : \ + No format error in certificate's notBefore field +The certificate notBefore field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD : \ + No format error in certificate's notAfter field +The certificate notAfter field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD : \ + No format error in CRL's lastUpdate field +The CRL lastUpdate field contains an invalid time. +.It Dv X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD : \ + No format error in CRL's nextUpdate field +The CRL nextUpdate field contains an invalid time. +.It Dv X509_V_ERR_OUT_OF_MEM : No out of memory +An error occurred trying to allocate memory. +This should never happen. +.It Dv X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT : No self signed certificate +The passed certificate is self signed and the same certificate cannot be +found in the list of trusted certificates. +.It Dv X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN : \ + No self signed certificate in certificate chain +The certificate chain could be built up using the untrusted certificates +but the root could not be found locally. +.It Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY : \ + No unable to get local issuer certificate +The issuer certificate of a locally looked up certificate could not be found. +This normally means the list of trusted certificates is not complete. +.It Dv X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE : \ + No unable to verify the first certificate +No signatures could be verified because the chain contains only one +certificate and it is not self signed. +.It Dv X509_V_ERR_CERT_CHAIN_TOO_LONG : No certificate chain too long +The certificate chain length is greater than the supplied maximum depth. +Unused. +.It Dv X509_V_ERR_CERT_REVOKED : No certificate revoked +The certificate has been revoked. +.It Dv X509_V_ERR_INVALID_CA : No invalid CA certificate +A CA certificate is invalid. +Either it is not a CA or its extensions are not consistent with the +supplied purpose. +.It Dv X509_V_ERR_PATH_LENGTH_EXCEEDED : No path length constraint exceeded +The basicConstraints pathlength parameter has been exceeded. +.It Dv X509_V_ERR_INVALID_PURPOSE : No unsupported certificate purpose +The supplied certificate cannot be used for the specified purpose. +.It Dv X509_V_ERR_CERT_UNTRUSTED : No certificate not trusted +The root CA is not marked as trusted for the specified purpose. +.It Dv X509_V_ERR_CERT_REJECTED : No certificate rejected +The root CA is marked to reject the specified purpose. +.It Dv X509_V_ERR_SUBJECT_ISSUER_MISMATCH : No subject issuer mismatch +The current candidate issuer certificate was rejected because its +subject name did not match the issuer name of the current certificate. +This is only set if issuer check debugging is enabled it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_AKID_SKID_MISMATCH : \ + No authority and subject key identifier mismatch +The current candidate issuer certificate was rejected because its +subject key identifier was present and did not match the authority key +identifier current certificate. +This is only set if issuer check debugging is enabled it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH : \ + Noauthority and issuer serial number mismatch +The current candidate issuer certificate was rejected because its issuer +name and serial number was present and did not match the authority key +identifier of the current certificate. +This is only set if issuer check debugging is enabled it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_KEYUSAGE_NO_CERTSIGN : \ + No key usage does not include certificate signing +The current candidate issuer certificate was rejected because its +keyUsage extension does not permit certificate signing. +This is only set if issuer check debugging is enabled it is used for +status notification and is +.Sy not +in itself an error. +.It Dv X509_V_ERR_INVALID_EXTENSION : \ + No invalid or inconsistent certificate extension +A certificate extension had an invalid value (for example an incorrect +encoding) or some value inconsistent with other extensions. +.It Dv X509_V_ERR_INVALID_POLICY_EXTENSION : \ + No invalid or inconsistent certificate policy extension +A certificate policies extension had an invalid value (for example an +incorrect encoding) or some value inconsistent with other extensions. +This error only occurs if policy processing is enabled. +.It Dv X509_V_ERR_NO_EXPLICIT_POLICY : No no explicit policy +The verification flags were set to require and explicit policy but none +was present. +.It Dv X509_V_ERR_DIFFERENT_CRL_SCOPE : No different CRL scope +The only CRLs that could be found did not match the scope of the +certificate. +.It Dv X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE : \ + No unsupported extension feature +Some feature of a certificate extension is not supported. +Unused. +.It Dv X509_V_ERR_PERMITTED_VIOLATION : No permitted subtree violation +A name constraint violation occurred in the permitted subtrees. +.It Dv X509_V_ERR_EXCLUDED_VIOLATION : No excluded subtree violation +A name constraint violation occurred in the excluded subtrees. +.It Dv X509_V_ERR_SUBTREE_MINMAX : \ + No name constraints minimum and maximum not supported +A certificate name constraints extension included a minimum or maximum +field: this is not supported. +.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE : \ + No unsupported name constraint type +An unsupported name constraint type was encountered. +OpenSSL currently only supports directory name, DNS name, email and URI +types. +.It Dv X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX : \ + No unsupported or invalid name constraint syntax +The format of the name constraint is not recognised: for example an +email address format of a form not mentioned in RFC3280. +This could be caused by a garbage extension or some new feature not +currently supported. +.It Dv X509_V_ERR_CRL_PATH_VALIDATION_ERROR : No CRL path validation error +An error occurred when attempting to verify the CRL path. +This error can only happen if extended CRL checking is enabled. +.It Dv X509_V_ERR_APPLICATION_VERIFICATION : \ + No application verification failure +An application specific error. +This will never be returned unless explicitly set by an application. +.El +.Sh SEE ALSO +.Xr X509_verify_cert 3 diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_get_ex_new_index.3 b/src/lib/libcrypto/man/X509_STORE_CTX_get_ex_new_index.3 new file mode 100644 index 0000000000..511933d4a1 --- /dev/null +++ b/src/lib/libcrypto/man/X509_STORE_CTX_get_ex_new_index.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_STORE_CTX_GET_EX_NEW_INDEX 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_get_ex_new_index , +.Nm X509_STORE_CTX_set_ex_data , +.Nm X509_STORE_CTX_get_ex_data +.Nd add application specific data to X509_STORE_CTX structures +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft int +.Fo X509_STORE_CTX_get_ex_new_index +.Fa "long argl" +.Fa "void *argp" +.Fa "CRYPTO_EX_new *new_func" +.Fa "CRYPTO_EX_dup *dup_func" +.Fa "CRYPTO_EX_free *free_func" +.Fc +.Ft int +.Fo X509_STORE_CTX_set_ex_data +.Fa "X509_STORE_CTX *d" +.Fa "int idx" +.Fa "void *arg" +.Fc +.Ft void * +.Fo X509_STORE_CTX_get_ex_data +.Fa "X509_STORE_CTX *d" +.Fa "int idx" +.Fc +.Sh DESCRIPTION +These functions handle application specific data in +.Vt X509_STORE_CTX +structures. +Their usage is identical to that of +.Xr RSA_get_ex_new_index 3 , +.Xr RSA_set_ex_data 3 , +and +.Xr RSA_get_ex_data 3 . +.Pp +This mechanism is used internally by the +.Xr ssl 3 +library to store the +.Vt SSL +structure associated with a verification operation in an +.Vt X509_STORE_CTX +structure. +.Sh SEE ALSO +.Xr RSA_get_ex_new_index 3 +.Sh HISTORY +.Fn X509_STORE_CTX_get_ex_new_index , +.Fn X509_STORE_CTX_set_ex_data , +and +.Fn X509_STORE_CTX_get_ex_data +are available since OpenSSL 0.9.5. diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_new.3 b/src/lib/libcrypto/man/X509_STORE_CTX_new.3 new file mode 100644 index 0000000000..6a4b9e3e53 --- /dev/null +++ b/src/lib/libcrypto/man/X509_STORE_CTX_new.3 @@ -0,0 +1,229 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_STORE_CTX_NEW 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_new , +.Nm X509_STORE_CTX_cleanup , +.Nm X509_STORE_CTX_free , +.Nm X509_STORE_CTX_init , +.Nm X509_STORE_CTX_trusted_stack , +.Nm X509_STORE_CTX_set_cert , +.Nm X509_STORE_CTX_set_chain , +.Nm X509_STORE_CTX_set0_crls , +.Nm X509_STORE_CTX_get0_param , +.Nm X509_STORE_CTX_set0_param , +.Nm X509_STORE_CTX_set_default +.Nd X509_STORE_CTX initialisation +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft X509_STORE_CTX * +.Fn X509_STORE_CTX_new void +.Ft void +.Fo X509_STORE_CTX_cleanup +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_free +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft int +.Fo X509_STORE_CTX_init +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_STORE *store" +.Fa "X509 *x509" +.Fa "STACK_OF(X509) *chain" +.Fc +.Ft void +.Fo X509_STORE_CTX_trusted_stack +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509) *sk" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_cert +.Fa "X509_STORE_CTX *ctx" +.Fa "X509 *x" +.Fc +.Ft void +.Fo X509_STORE_CTX_set_chain +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509) *sk" +.Fc +.Ft void +.Fo X509_STORE_CTX_set0_crls +.Fa "X509_STORE_CTX *ctx" +.Fa "STACK_OF(X509_CRL) *sk" +.Fc +.Ft X509_VERIFY_PARAM * +.Fo X509_STORE_CTX_get0_param +.Fa "X509_STORE_CTX *ctx" +.Fc +.Ft void +.Fo X509_STORE_CTX_set0_param +.Fa "X509_STORE_CTX *ctx" +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_STORE_CTX_set_default +.Fa "X509_STORE_CTX *ctx" +.Fa "const char *name" +.Fc +.Sh DESCRIPTION +These functions initialise an +.Vt X509_STORE_CTX +structure for subsequent use by +.Xr X509_verify_cert 3 . +.Pp +.Fn X509_STORE_CTX_new +returns a newly initialised +.Vt X509_STORE_CTX +structure. +.Pp +.Fn X509_STORE_CTX_cleanup +internally cleans up an +.Vt X509_STORE_CTX +structure. +The context can then be reused with an new call to +.Fn X509_STORE_CTX_init . +.Pp +.Fn X509_STORE_CTX_free +completely frees up +.Fa ctx . +After this call +.Fa ctx +is no longer valid. +.Pp +.Fn X509_STORE_CTX_init +sets up +.Fa ctx +for a subsequent verification operation. +The trusted certificate store is set to +.Fa store , +the end entity certificate to be verified is set to +.Fa x509 +and a set of additional certificates (which will be untrusted but may be +used to build the chain) in +.Fa chain . +Any or all of the +.Fa store , +.Fa x509 , +and +.Fa chain +parameters can be +.Dv NULL . +.Pp +.Fn X509_STORE_CTX_trusted_stack +sets the set of trusted certificates of +.Fa ctx +to +.Fa sk . +This is an alternative way of specifying trusted certificates instead of +using an +.Vt X509_STORE . +.Pp +.Fn X509_STORE_CTX_set_cert +sets the certificate to be verified in +.Fa ctx +to +.Fa x . +.Pp +.Fn X509_STORE_CTX_set_chain +sets the additional certificate chain used by +.Fa ctx +to +.Fa sk . +.Pp +.Fn X509_STORE_CTX_set0_crls +sets a set of CRLs to use to aid certificate verification to +.Fa sk . +These CRLs will only be used if CRL verification is enabled in the +associated +.Vt X509_VERIFY_PARAM +structure. +This might be used where additional "useful" CRLs are supplied as part +of a protocol, for example in a PKCS#7 structure. +.Pp +X509_VERIFY_PARAM +.Fn X509_STORE_CTX_get0_param +retrieves an internal pointer to the verification parameters associated +with +.Fa ctx . +.Pp +.Fn X509_STORE_CTX_set0_param +sets the internal verification parameter pointer to +.Fa param . +After this call +.Fa param +should not be used. +.Pp +.Fn X509_STORE_CTX_set_default +looks up and sets the default verification method to +.Fa name . +This uses the function +.Xr X509_VERIFY_PARAM_lookup 3 +to find an appropriate set of parameters from +.Fa name . +.Pp +The certificates and CRLs in a store are used internally and should +.Sy not +be freed up until after the associated +.Vt X509_STORE_CTX +is freed. +Legacy applications might implicitly use an +.Vt X509_STORE_CTX +like this: +.Bd -literal -offset indent +X509_STORE_CTX ctx; +X509_STORE_CTX_init(&ctx, store, cert, chain); +.Ed +.Pp +This is +.Sy not +recommended in new applications they should instead do: +.Bd -literal -offset indent +X509_STORE_CTX *ctx; +ctx = X509_STORE_CTX_new(); +if (ctx == NULL) + /* Bad error */ +X509_STORE_CTX_init(ctx, store, cert, chain); +.Ed +.Sh RETURN VALUES +.Fn X509_STORE_CTX_new +returns an newly allocates context or +.Dv NULL +if an error occurred. +.Pp +.Fn X509_STORE_CTX_init +returns 1 for success or 0 if an error occurred. +.Pp +.Fn X509_STORE_CTX_get0_param +returns a pointer to an +.Vt X509_VERIFY_PARAM +structure or +.Dv NULL +if an error occurred. +.Pp +.Fn X509_STORE_CTX_cleanup , +.Fn X509_STORE_CTX_free , +.Fn X509_STORE_CTX_trusted_stack , +.Fn X509_STORE_CTX_set_cert , +.Fn X509_STORE_CTX_set_chain , +.Fn X509_STORE_CTX_set0_crls , +and +.Fn X509_STORE_CTX_set0_param +do not return values. +.Pp +.Fn X509_STORE_CTX_set_default +returns 1 for success or 0 if an error occurred. +.Sh SEE ALSO +.Xr X509_verify_cert 3 , +.Xr X509_VERIFY_PARAM_set_flags 3 +.Sh HISTORY +.Fn X509_STORE_CTX_set0_crls +was first added to OpenSSL 1.0.0. +.Sh BUGS +The certificates and CRLs in a context are used internally and should +.Sy not +be freed up until after the associated +.Vt X509_STORE_CTX +is freed. +Copies should be made or reference counts increased instead. diff --git a/src/lib/libcrypto/man/X509_STORE_CTX_set_verify_cb.3 b/src/lib/libcrypto/man/X509_STORE_CTX_set_verify_cb.3 new file mode 100644 index 0000000000..f588bd7d70 --- /dev/null +++ b/src/lib/libcrypto/man/X509_STORE_CTX_set_verify_cb.3 @@ -0,0 +1,185 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_STORE_CTX_SET_VERIFY_CB 3 +.Os +.Sh NAME +.Nm X509_STORE_CTX_set_verify_cb +.Nd set verification callback +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft void +.Fo X509_STORE_CTX_set_verify_cb +.Fa "X509_STORE_CTX *ctx" +.Fa "int (*verify_cb)(int ok, X509_STORE_CTX *ctx)" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_CTX_set_verify_cb +sets the verification callback of +.Fa ctx +to +.Fa verify_cb +overwriting any existing callback. +.Pp +The verification callback can be used to customise the operation of +certificate verification, either by overriding error conditions or +logging errors for debugging purposes. +.Pp +However a verification callback is +.Sy not +essential and the default operation is often sufficient. +.Pp +The +.Fa ok +parameter to the callback indicates the value the callback should return +to retain the default behaviour. +If it is zero then and error condition is indicated. +If it is 1 then no error occurred. +If the flag +.Dv X509_V_FLAG_NOTIFY_POLICY +is set, then +.Fa ok +is set to 2 to indicate the policy checking is complete. +.Pp +The +.Fa ctx +parameter to the callback is the +.Vt X509_STORE_CTX +structure that is performing the verification operation. +A callback can examine this structure and receive additional information +about the error, for example by calling +.Xr X509_STORE_CTX_get_current_cert 3 . +Additional application data can be passed to the callback via the +.Sy ex_data +mechanism. +.Pp +The verification callback can be set and inherited from the parent +structure performing the operation. +In some cases (such as S/MIME verification) the +.Vt X509_STORE_CTX +structure is created and destroyed internally and the only way to set a +custom verification callback is by inheriting it from the associated +.Vt X509_STORE . +.Sh RETURN VALUES +.Fn X509_STORE_CTX_set_verify_cb +does not return a value. +.Sh EXAMPLES +Default callback operation: +.Bd -literal +int +verify_callback(int ok, X509_STORE_CTX *ctx) + { + return ok; +} +.Ed +.Pp +Simple example, suppose a certificate in the chain is expired and we +wish to continue after this error: +.Bd -literal +int +verify_callback(int ok, X509_STORE_CTX *ctx) +{ + /* Tolerate certificate expiration */ + if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) + return 1; + /* Otherwise don't override */ + return ok; +} +.Ed +.Pp +More complex example, we don't wish to continue after +.Sy any +certificate has expired just one specific case: +.Bd -literal +int +verify_callback(int ok, X509_STORE_CTX *ctx) +{ + int err = X509_STORE_CTX_get_error(ctx); + X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); + + if (err == X509_V_ERR_CERT_HAS_EXPIRED) { + if (check_is_acceptable_expired_cert(err_cert) + return 1; + } + return ok; +} +.Ed +.Pp +Full featured logging callback. +In this case the +.Fa bio_err +is assumed to be a global logging +.Vt BIO , +an alternative would to store a +.Vt BIO +in +.Fa ctx +using +.Sy ex_data . +.Bd -literal +int +verify_callback(int ok, X509_STORE_CTX *ctx) +{ + X509 *err_cert; + int err,depth; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + BIO_printf(bio_err,"depth=%d ",depth); + if (err_cert) { + X509_NAME_print_ex(bio_err, + X509_get_subject_name(err_cert), 0, + XN_FLAG_ONELINE); + BIO_puts(bio_err, "\en"); + } else + BIO_puts(bio_err, "\en"); + if (!ok) + BIO_printf(bio_err, "verify error:num=%d:%s\en", + err, X509_verify_cert_error_string(err)); + switch (err) { + case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: + BIO_puts(bio_err, "issuer= "); + X509_NAME_print_ex(bio_err, + X509_get_issuer_name(err_cert), 0, + XN_FLAG_ONELINE); + BIO_puts(bio_err, "\en"); + break; + case X509_V_ERR_CERT_NOT_YET_VALID: + case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: + BIO_printf(bio_err, "notBefore="); + ASN1_TIME_print(bio_err, + X509_get_notBefore(err_cert)); + BIO_printf(bio_err, "\en"); + break; + case X509_V_ERR_CERT_HAS_EXPIRED: + case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: + BIO_printf(bio_err, "notAfter="); + ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); + BIO_printf(bio_err, "\en"); + break; + case X509_V_ERR_NO_EXPLICIT_POLICY: + policies_print(bio_err, ctx); + break; + } + if (err == X509_V_OK && ok == 2) + /* print out policies */ + + BIO_printf(bio_err,"verify return:%d\en",ok); + return(ok); +} +.Ed +.Sh SEE ALSO +.Xr X509_STORE_CTX_get_error 3 , +.Xr X509_STORE_CTX_get_ex_new_index 3 , +.Xr X509_STORE_set_verify_cb_func 3 +.Sh HISTORY +.Fn X509_STORE_CTX_set_verify_cb +is available in all versions of SSLeay and OpenSSL. +.Sh CAVEATS +In general a verification callback should +.Sy NOT +unconditionally return 1 in all circumstances because this will allow +verification to succeed no matter what the error. +This effectively removes all security from the application because +.Sy any +certificate (including untrusted generated ones) will be accepted. diff --git a/src/lib/libcrypto/man/X509_STORE_set_verify_cb_func.3 b/src/lib/libcrypto/man/X509_STORE_set_verify_cb_func.3 new file mode 100644 index 0000000000..5db4313047 --- /dev/null +++ b/src/lib/libcrypto/man/X509_STORE_set_verify_cb_func.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_STORE_SET_VERIFY_CB_FUNC 3 +.Os +.Sh NAME +.Nm X509_STORE_set_verify_cb_func , +.Nm X509_STORE_set_verify_cb +.Nd set verification callback +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft void +.Fo X509_STORE_set_verify_cb +.Fa "X509_STORE *st" +.Fa "int (*verify_cb)(int ok, X509_STORE_CTX *ctx)" +.Fc +.Ft void +.Fo X509_STORE_set_verify_cb_func +.Fa "X509_STORE *st" +.Fa "int (*verify_cb)(int ok, X509_STORE_CTX *ctx)" +.Fc +.Sh DESCRIPTION +.Fn X509_STORE_set_verify_cb +sets the verification callback of +.Sy ctx +to +.Sy verify_cb +overwriting any existing callback. +.Pp +.Fn X509_STORE_set_verify_cb_func +also sets the verification callback but it is implemented as a macro. +.Pp +The verification callback from an +.Vt X509_STORE +is inherited by the corresponding +.Vt X509_STORE_CTX +structure when it is initialized. +This can be used to set the verification callback when the +.Vt X509_STORE_CTX +is otherwise inaccessible (for example during S/MIME verification). +.Sh RETURN VALUES +.Fn X509_STORE_set_verify_cb +and +.Fn X509_STORE_set_verify_cb_func +do not return a value. +.Sh SEE ALSO +.Xr X509_STORE_CTX_set_verify_cb 3 +.Sh HISTORY +.Fn X509_STORE_set_verify_cb_func +is available in all versions of SSLeay and OpenSSL. +.Pp +.Fn X509_STORE_set_verify_cb +was added to OpenSSL 1.0.0. +.Sh BUGS +The macro version of this function was the only one available before +OpenSSL 1.0.0. diff --git a/src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 b/src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 new file mode 100644 index 0000000000..66724ed169 --- /dev/null +++ b/src/lib/libcrypto/man/X509_VERIFY_PARAM_set_flags.3 @@ -0,0 +1,271 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_VERIFY_PARAM_SET_FLAGS 3 +.Os +.Sh NAME +.Nm X509_VERIFY_PARAM_set_flags , +.Nm X509_VERIFY_PARAM_clear_flags , +.Nm X509_VERIFY_PARAM_get_flags , +.Nm X509_VERIFY_PARAM_set_purpose , +.Nm X509_VERIFY_PARAM_set_trust , +.Nm X509_VERIFY_PARAM_set_depth , +.Nm X509_VERIFY_PARAM_get_depth , +.Nm X509_VERIFY_PARAM_set_time , +.Nm X509_VERIFY_PARAM_add0_policy , +.Nm X509_VERIFY_PARAM_set1_policies +.Nd X509 verification parameters +.Sh SYNOPSIS +.In openssl/x509_vfy.h +.Ft int +.Fo X509_VERIFY_PARAM_set_flags +.Fa "X509_VERIFY_PARAM *param" +.Fa "unsigned long flags" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_clear_flags +.Fa "X509_VERIFY_PARAM *param" +.Fa "unsigned long flags" +.Fc +.Ft unsigned long +.Fo X509_VERIFY_PARAM_get_flags +.Fa "X509_VERIFY_PARAM *param" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set_purpose +.Fa "X509_VERIFY_PARAM *param" +.Fa "int purpose" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set_trust +.Fa "X509_VERIFY_PARAM *param" +.Fa "int trust" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_set_time +.Fa "X509_VERIFY_PARAM *param" +.Fa "time_t t" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_add0_policy +.Fa "X509_VERIFY_PARAM *param" +.Fa "ASN1_OBJECT *policy" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_set1_policies +.Fa "X509_VERIFY_PARAM *param" +.Fa "STACK_OF(ASN1_OBJECT) *policies" +.Fc +.Ft void +.Fo X509_VERIFY_PARAM_set_depth +.Fa "X509_VERIFY_PARAM *param" +.Fa "int depth" +.Fc +.Ft int +.Fo X509_VERIFY_PARAM_get_depth +.Fa "const X509_VERIFY_PARAM *param" +.Fc +.Sh DESCRIPTION +These functions manipulate the +.Vt X509_VERIFY_PARAM +structure associated with a certificate verification operation. +.Pp +The +.Fn X509_VERIFY_PARAM_set_flags +function sets the flags in +.Fa param +by OR'ing it with +.Fa flags . +See the +.Sx VERIFICATION FLAGS +section for a complete description of values the +.Fa flags +parameter can take. +.Pp +.Fn X509_VERIFY_PARAM_get_flags +returns the flags in +.Fa param . +.Pp +.Fn X509_VERIFY_PARAM_clear_flags +clears the flags +.Fa flags +in +.Fa param . +.Pp +.Fn X509_VERIFY_PARAM_set_purpose +sets the verification purpose in +.Fa param +to +.Fa purpose . +This determines the acceptable purpose of the certificate chain, for +example SSL client or SSL server. +.Pp +.Fn X509_VERIFY_PARAM_set_trust +sets the trust setting in +.Fa param +to +.Fa trust . +.Pp +.Fn X509_VERIFY_PARAM_set_time +sets the verification time in +.Fa param +to +.Fa t . +Normally the current time is used. +.Pp +.Fn X509_VERIFY_PARAM_add0_policy +enables policy checking (it is disabled by default) and adds +.Fa policy +to the acceptable policy set. +.Pp +.Fn X509_VERIFY_PARAM_set1_policies +enables policy checking (it is disabled by default) and sets the +acceptable policy set to +.Fa policies . +Any existing policy set is cleared. +The +.Fa policies +parameter can be +.Dv NULL +to clear an existing policy set. +.Pp +.Fn X509_VERIFY_PARAM_set_depth +sets the maximum verification depth to +.Fa depth . +That is the maximum number of untrusted CA certificates that can appear +in a chain. +.Pp +The above functions should be used to manipulate verification parameters +instead of legacy functions which work in specific structures such as +.Xr X509_STORE_CTX_set_flags 3 . +.Sh RETURN VALUES +.Fn X509_VERIFY_PARAM_set_flags , +.Fn X509_VERIFY_PARAM_clear_flags , +.Fn X509_VERIFY_PARAM_set_purpose , +.Fn X509_VERIFY_PARAM_set_trust , +.Fn X509_VERIFY_PARAM_add0_policy , +and +.Fn X509_VERIFY_PARAM_set1_policies +return 1 for success or 0 for failure. +.Pp +.Fn X509_VERIFY_PARAM_get_flags +returns the current verification flags. +.Pp +.Fn X509_VERIFY_PARAM_set_time +and +.Fn X509_VERIFY_PARAM_set_depth +do not return values. +.Pp +.Fn X509_VERIFY_PARAM_get_depth +returns the current verification depth. +.Sh VERIFICATION FLAGS +The verification flags consists of zero or more of the following +flags OR'ed together. +.Pp +.Dv X509_V_FLAG_CRL_CHECK +enables CRL checking for the certificate chain leaf certificate. +An error occurs if a suitable CRL cannot be found. +.Pp +.Dv X509_V_FLAG_CRL_CHECK_ALL +enables CRL checking for the entire certificate chain. +.Pp +.Dv X509_V_FLAG_IGNORE_CRITICAL +disabled critical extension checking. +By default any unhandled critical extensions in certificates or (if +checked) CRLs results in a fatal error. +If this flag is set unhandled critical extensions are ignored. +.Sy WARNING : +setting this option for anything other than debugging purposes can be a +security risk. +Finer control over which extensions are supported can be performed in +the verification callback. +.Pp +The +.Dv X509_V_FLAG_X509_STRICT +flag disables workarounds for some broken certificates and makes the +verification strictly apply X509 rules. +.Pp +.Dv X509_V_FLAG_ALLOW_PROXY_CERTS +enables proxy certificate verification. +.Pp +.Dv X509_V_FLAG_POLICY_CHECK +enables certificate policy checking, by default no policy checking is +performed. +Additional information is sent to the verification callback relating to +policy checking. +.Pp +.Dv X509_V_FLAG_EXPLICIT_POLICY , +.Dv X509_V_FLAG_INHIBIT_ANY , +and +.Dv X509_V_FLAG_INHIBIT_MAP +set the +.Dq require explicit policy , +.Dq inhibit any policy , +and +.Dq inhibit policy mapping +flags, respectively, as defined in RFC3280. +Policy checking is automatically enabled if any of these flags are set. +.Pp +If +.Dv X509_V_FLAG_NOTIFY_POLICY +is set and the policy checking is successful a special status code is +set to the verification callback. +This permits it to examine the valid policy tree and perform additional +checks or simply log it for debugging purposes. +.Pp +By default some additional features such as indirect CRLs and CRLs +signed by different keys are disabled. +If +.Dv X509_V_FLAG_EXTENDED_CRL_SUPPORT +is set they are enabled. +.Pp +If +.Dv X509_V_FLAG_USE_DELTAS +is set, delta CRLs (if present) are used to determine certificate +status. +If not set, deltas are ignored. +.Pp +.Dv X509_V_FLAG_CHECK_SS_SIGNATURE +enables checking of the root CA self signed certificate signature. +By default this check is disabled because it doesn't add any additional +security but in some cases applications might want to check the +signature anyway. +A side effect of not checking the root CA signature is that disabled or +unsupported message digests on the root CA are not treated as fatal +errors. +.Pp +The +.Dv X509_V_FLAG_CB_ISSUER_CHECK +flag enables debugging of certificate issuer checks. +It is +.Sy not +needed unless you are logging certificate verification. +If this flag is set then additional status codes will be sent to the +verification callback and it +.Sy must +be prepared to handle such cases without assuming they are hard errors. +.Sh EXAMPLES +Enable CRL checking when performing certificate verification during +SSL connections associated with an +.Vt SSL_CTX +structure +.Fa ctx : +.Bd -literal +X509_VERIFY_PARAM *param; +param = X509_VERIFY_PARAM_new(); +X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); +SSL_CTX_set1_param(ctx, param); +X509_VERIFY_PARAM_free(param); +.Ed +.Sh SEE ALSO +.Xr X509_verify_cert 3 +.Sh BUGS +Delta CRL checking is currently primitive. +Only a single delta can be used and (partly due to limitations of +.Vt X509_STORE ) +constructed CRLs are not maintained. +.Pp +If CRLs checking is enabled, CRLs are expected to be available in +the corresponding +.Vt X509_STORE +structure. +No attempt is made to download CRLs from the CRL distribution points +extension. diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3 new file mode 100644 index 0000000000..26c46ae3a9 --- /dev/null +++ b/src/lib/libcrypto/man/X509_new.3 @@ -0,0 +1,49 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_NEW 3 +.Os +.Sh NAME +.Nm X509_new , +.Nm X509_free +.Nd X509 certificate ASN1 allocation functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509 * +.Fn X509_new void +.Ft void +.Fo X509_free +.Fa "X509 *a" +.Fc +.Sh DESCRIPTION +The X509 ASN1 allocation routines allocate and free an +.Vt X509 +structure, which represents an X509 certificate. +.Pp +.Fn X509_new +allocates and initializes a X509 structure. +.Pp +.Fn X509_free +frees up the +.Vt X509 +structure +.Fa a . +If +.Fa a +is a +.Dv NULL +pointer, no action occurs. +.Sh RETURN VALUES +If the allocation fails, +.Fn X509_new +returns +.Dv NULL +and sets an error code that can be obtained by +.Xr ERR_get_error 3 . +Otherwise it returns a pointer to the newly allocated structure. +.Sh SEE ALSO +.Xr d2i_X509 3 , +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn X509_new +and +.Fn X509_free +are available in all versions of SSLeay and OpenSSL. diff --git a/src/lib/libcrypto/man/X509_verify_cert.3 b/src/lib/libcrypto/man/X509_verify_cert.3 new file mode 100644 index 0000000000..fd3d6bebda --- /dev/null +++ b/src/lib/libcrypto/man/X509_verify_cert.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509_VERIFY_CERT 3 +.Os +.Sh NAME +.Nm X509_verify_cert +.Nd discover and verify X509 certificate chain +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_verify_cert +.Fa "X509_STORE_CTX *ctx" +.Fc +.Sh DESCRIPTION +The +.Fn X509_verify_cert +function attempts to discover and validate a certificate chain based on +parameters in +.Fa ctx . +.Pp +Applications rarely call this function directly, but it is used by +OpenSSL internally for certificate validation, in both the S/MIME and +SSL/TLS code. +.Sh RETURN VALUES +If a complete chain can be built and validated this function returns 1, +otherwise it return 0. +.Pp +In exceptional circumstances, it can also return a negative code, +but only if no certificate is set in +.Fa ctx +due to a programming error or if a retry operation is requested +during internal lookups, which never happens with standard lookup +methods. +It is however recommended that application check for <= 0 return +value on error. +.Pp +If the function fails, additional error information can be obtained +by examining +.Fa ctx , +for example using +.Xr X509_STORE_CTX_get_error 3 . +.Sh SEE ALSO +.Xr X509_STORE_CTX_get_error 3 +and the +.Cm verify +entry in +.Xr openssl 1 +.Sh HISTORY +.Fn X509_verify_cert +is available in all versions of SSLeay and OpenSSL. +.Sh BUGS +This function uses the header +.In openssl/x509.h +as opposed to most chain verification functions which use +.In openssl/x509_vfy.h . diff --git a/src/lib/libcrypto/man/d2i_X509.3 b/src/lib/libcrypto/man/d2i_X509.3 new file mode 100644 index 0000000000..09c65afa58 --- /dev/null +++ b/src/lib/libcrypto/man/d2i_X509.3 @@ -0,0 +1,346 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt D2I_X509 3 +.Os +.Sh NAME +.Nm d2i_X509 , +.Nm i2d_X509 , +.Nm d2i_X509_bio , +.Nm d2i_X509_fp , +.Nm i2d_X509_bio , +.Nm i2d_X509_fp +.Nd X509 encode and decode functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509 * +.Fo d2i_X509 +.Fa "X509 **px" +.Fa "const unsigned char **in" +.Fa "int len" +.Fc +.Ft int +.Fo i2d_X509 +.Fa "X509 *x" +.Fa "unsigned char **out" +.Fc +.Ft X509 * +.Fo d2i_X509_bio +.Fa "BIO *bp" +.Fa "X509 **x" +.Fc +.Ft X509 * +.Fo d2i_X509_fp +.Fa "FILE *fp" +.Fa "X509 **x" +.Fc +.Ft int +.Fo i2d_X509_bio +.Fa "BIO *bp" +.Fa "X509 *x" +.Fc +.Ft int +.Fo i2d_X509_fp +.Fa "FILE *fp" +.Fa "X509 *x" +.Fc +.Sh DESCRIPTION +The X509 encode and decode routines encode and parse an +.Vt X509 +structure, which represents an X509 certificate. +.Pp +.Fn d2i_X509 +attempts to decode +.Fa len +bytes at +.Pf * Fa in . +If successful, a pointer to the +.Vt X509 +structure is returned. +If an error occurred, +.Dv NULL +is returned. +If +.Fa px +is not +.Dv NULL , +the returned structure is written to +.Pf * Fa px . +If +.Pf * Fa px +is not +.Dv NULL , +then it is assumed that +.Pf * Fa px +contains a valid +.Vt X509 +structure and an attempt is made to reuse it. +If the call is successful, +.Pf * Fa in +is incremented to the byte following the parsed data. +.Pp +.Fn i2d_X509 +encodes the structure pointed to by +.Fa x +into DER format. +If +.Fa out +is not +.Dv NULL , +it writes the DER encoded data to the buffer at +.Pf * Fa out +and increments it to point after the data just written. +If the return value is negative an error occurred, otherwise it returns +the length of the encoded data. +.Pp +For OpenSSL 0.9.7 and later if +.Pf * Fa out +is +.Dv NULL , +memory will be allocated for a buffer and the encoded data written to it. +In this case +.Pf * Fa out +is not incremented and it points to the start of the data just written. +.Pp +.Fn d2i_X509_bio +is similar to +.Fn d2i_X509 +except it attempts to parse data from +.Vt BIO +.Fa bp . +.Pp +.Fn d2i_X509_fp +is similar to +.Fn d2i_X509 +except it attempts to parse data from the +.Vt FILE +pointer +.Fa fp . +.Pp +.Fn i2d_X509_bio +is similar to +.Fn i2d_X509 +except it writes the encoding of the structure +.Fa x +to +.Vt BIO +.Fa bp +and it returns 1 for success or 0 for failure. +.Pp +.Fn i2d_X509_fp +is similar to +.Fn i2d_X509 +except it writes the encoding of the structure +.Fa x +to +.Vt BIO +.Fa bp +and it returns 1 for success or 0 for failure. +.Pp +The letters +.Sy i +and +.Sy d +in for example +.Fn i2d_X509 +stand for "internal" (that is an internal C structure) and "DER", +so that +.Fn i2d_X509 +converts from internal to DER. +.Pp +The functions can also understand BER forms. +.Pp +The actual +.Vt X509 +structure passed to +.Fn i2d_X509 +must be a valid populated +.Vt X509 +structure. +It cannot simply be fed with an empty structure such as that returned by +.Xr X509_new 3 . +.Pp +The encoded data is in binary form and may contain embedded zeroes. +Therefore any +.Vt FILE +pointers or +.Vt BIO Ns s +should be opened in binary mode. +Functions such as +.Xr strlen 3 +will +.Sy not +return the correct length of the encoded structure. +.Pp +The ways that +.Pf * Fa in +and +.Pf * Fa out +are incremented after the operation can trap the unwary. +See the +.Sx CAVEATS +section for some common errors. +.Pp +The reason for the auto increment behaviour is to reflect a typical +usage of ASN1 functions: after one structure is encoded or decoded, +another will processed after it. +.Sh RETURN VALUES +.Fn d2i_X509 , +.Fn d2i_X509_bio , +and +.Fn d2i_X509_fp +return a valid +.Vt X509 +structure or +.Dv NULL +if an error occurs. +.Pp +.Fn i2d_X509 +returns the number of bytes successfully encoded or a negative value if +an error occurs. +.Pp +.Fn i2d_X509_bio +and +.Fn i2d_X509_fp +return 1 for success or 0 if an error occurs. +.Pp +For all functions, the error code can be obtained by +.Xr ERR_get_error 3 . +.Sh EXAMPLES +Allocate and encode the DER encoding of an X509 structure: +.Bd -literal -offset indent +int len; +unsigned char *buf, *p; + +len = i2d_X509(x, NULL); +buf = malloc(len); +if (buf == NULL) + /* error */ +p = buf; +i2d_X509(x, &p); +.Ed +.Pp +If you are using OpenSSL 0.9.7 or later then this can be simplified to: +.Bd -literal -offset indent +int len; +unsigned char *buf; + +buf = NULL; +len = i2d_X509(x, &buf); +if (len < 0) + /* error */ +.Ed +.Pp +Attempt to decode a buffer: +.Bd -literal -offset indent +X509 *x; +unsigned char *buf, *p; +int len; + +/* Something to setup buf and len */ +p = buf; +x = d2i_X509(NULL, &p, len); +if (x == NULL) + /* Some error */ +.Ed +.Pp +Alternative technique: +.Bd -literal -offset indent +X509 *x; +unsigned char *buf, *p; +int len; + +/* Something to setup buf and len */ +p = buf; +x = NULL; +if(!d2i_X509(&x, &p, len)) + /* Some error */ +.Ed +.Sh SEE ALSO +.Xr ERR_get_error 3 +.Sh HISTORY +.Fn d2i_X509 , +.Fn i2d_X509 , +.Fn d2i_X509_bio , +.Fn d2i_X509_fp , +.Fn i2d_X509_bio , +and +.Fn i2d_X509_fp +are available in all versions of SSLeay and OpenSSL. +.Sh CAVEATS +The use of a temporary variable is mandatory. +A common mistake is to attempt to use a buffer directly as follows: +.Bd -literal -offset indent +int len; +unsigned char *buf; + +len = i2d_X509(x, NULL); +buf = malloc(len); +if (buf == NULL) + /* error */ +i2d_X509(x, &buf); +/* Other stuff ... */ +free(buf); +.Ed +.Pp +This code will result in +.Fa buf +apparently containing garbage because it was incremented after the +call to point after the data just written. +Also +.Fa buf +will no longer contain the pointer allocated by +.Xr malloc 3 +and the subsequent call to +.Xr free 3 +may well crash. +.Pp +The auto allocation feature (setting +.Fa buf +to +.Dv NULL +only works on OpenSSL 0.9.7 and later. +Attempts to use it on earlier versions will typically cause a +segmentation violation. +.Pp +Another trap to avoid is misuse of the +.Fa px +argument to +.Sy d2i_X509() : +.Bd -literal -offset indent +X509 *x; + +if (!d2i_X509(&x, &p, len)) + /* Some error */ +.Ed +.Pp +This will probably crash somewhere in +.Fn d2i_X509 . +The reason for this is that the variable +.Fa x +is uninitialized and an attempt will be made to interpret its (invalid) +value as an +.Vt X509 +structure, typically causing a segmentation violation. +If +.Fa x +is set to +.Dv NULL +first then this will not happen. +.Sh BUGS +In some versions of OpenSSL the "reuse" behaviour of +.Fn d2i_X509 +when +.Pf * Fa px +is valid is broken and some parts of the reused structure may persist +if they are not present in the new one. +As a result the use of this "reuse" behaviour is strongly discouraged. +.Pp +In many versions of OpenSSL, +.Fn i2d_X509 +will not return an error if mandatory fields are not initialized +due to a programming error. +Then the encoded structure may contain invalid data or omit the +fields entirely and will not be parsed by +.Fn d2i_X509 . +This may be fixed in future so code should not assume that +.Fn i2d_X509 +will always succeed. diff --git a/src/lib/libcrypto/man/d2i_X509_ALGOR.3 b/src/lib/libcrypto/man/d2i_X509_ALGOR.3 new file mode 100644 index 0000000000..e17678019b --- /dev/null +++ b/src/lib/libcrypto/man/d2i_X509_ALGOR.3 @@ -0,0 +1,33 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt D2I_X509_ALGOR 3 +.Os +.Sh NAME +.Nm d2i_X509_ALGOR , +.Nm i2d_X509_ALGOR +.Nd AlgorithmIdentifier functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509_ALGOR * +.Fo d2i_X509_ALGOR +.Fa "X509_ALGOR **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_ALGOR +.Fa "X509_ALGOR *a" +.Fa "unsigned char **pp" +.Fc +.Sh DESCRIPTION +These functions decode and encode an +.Vt X509_ALGOR +structure which is equivalent to the +.Sy AlgorithmIdentifier +structure. +.Pp +Otherwise these behave in a way similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/d2i_X509_CRL.3 b/src/lib/libcrypto/man/d2i_X509_CRL.3 new file mode 100644 index 0000000000..e487da16d0 --- /dev/null +++ b/src/lib/libcrypto/man/d2i_X509_CRL.3 @@ -0,0 +1,54 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt D2I_X509_CRL 3 +.Os +.Sh NAME +.Nm d2i_X509_CRL , +.Nm i2d_X509_CRL , +.Nm d2i_X509_CRL_bio , +.Nm d2i_X509_CRL_fp , +.Nm i2d_X509_CRL_bio , +.Nm i2d_X509_CRL_fp +.Nd PKCS#10 certificate request functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509_CRL * +.Fo d2i_X509_CRL +.Fa "X509_CRL **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_CRL +.Fa "X509_CRL *a" +.Fa "unsigned char **pp" +.Fc +.Ft X509_CRL * +.Fo d2i_X509_CRL_bio +.Fa "BIO *bp" +.Fa "X509_CRL **x" +.Fc +.Ft X509_CRL * +.Fo d2i_X509_CRL_fp +.Fa "FILE *fp" +.Fa "X509_CRL **x" +.Fc +.Ft int +.Fo i2d_X509_CRL_bio +.Fa "BIO *bp" +.Fa "X509_CRL *x" +.Fc +.Ft int +.Fo i2d_X509_CRL_fp +.Fa "FILE *fp" +.Fa "X509_CRL *x" +.Fc +.Sh DESCRIPTION +These functions decode and encode an X509 CRL (certificate revocation +list). +.Pp +Otherwise the functions behave in a way similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/d2i_X509_NAME.3 b/src/lib/libcrypto/man/d2i_X509_NAME.3 new file mode 100644 index 0000000000..b145bf5b58 --- /dev/null +++ b/src/lib/libcrypto/man/d2i_X509_NAME.3 @@ -0,0 +1,34 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt D2I_X509_NAME 3 +.Os +.Sh NAME +.Nm d2i_X509_NAME , +.Nm i2d_X509_NAME +.Nd X509_NAME encoding functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509_NAME * +.Fo d2i_X509_NAME +.Fa "X509_NAME **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_NAME +.Fa "X509_NAME *a" +.Fa "unsigned char **pp" +.Fc +.Sh DESCRIPTION +These functions decode and encode an +.Vt X509_NAME +structure which is the same as the +.Sy Name +type defined in RFC2459 (and elsewhere) and used for example in +certificate subject and issuer names. +.Pp +Otherwise the functions behave in a way similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/d2i_X509_REQ.3 b/src/lib/libcrypto/man/d2i_X509_REQ.3 new file mode 100644 index 0000000000..c69cd00fb1 --- /dev/null +++ b/src/lib/libcrypto/man/d2i_X509_REQ.3 @@ -0,0 +1,53 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt D2I_X509_REQ 3 +.Os +.Sh NAME +.Nm d2i_X509_REQ , +.Nm i2d_X509_REQ , +.Nm d2i_X509_REQ_bio , +.Nm d2i_X509_REQ_fp , +.Nm i2d_X509_REQ_bio , +.Nm i2d_X509_REQ_fp +.Nd PKCS#10 certificate request functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509_REQ * +.Fo d2i_X509_REQ +.Fa "X509_REQ **a" +.Fa "const unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_REQ +.Fa "X509_REQ *a" +.Fa "unsigned char **pp" +.Fc +.Ft X509_REQ * +.Fo d2i_X509_REQ_bio +.Fa "BIO *bp" +.Fa "X509_REQ **x" +.Fc +.Ft X509_REQ * +.Fo d2i_X509_REQ_fp +.Fa "FILE *fp" +.Fa "X509_REQ **x" +.Fc +.Ft int +.Fo i2d_X509_REQ_bio +.Fa "BIO *bp" +.Fa "X509_REQ *x" +.Fc +.Ft int +.Fo i2d_X509_REQ_fp +.Fa "FILE *fp" +.Fa "X509_REQ *x" +.Fc +.Sh DESCRIPTION +These functions decode and encode a PKCS#10 certificate request. +.Pp +Otherwise these behave in a way similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/d2i_X509_SIG.3 b/src/lib/libcrypto/man/d2i_X509_SIG.3 new file mode 100644 index 0000000000..5356dd67de --- /dev/null +++ b/src/lib/libcrypto/man/d2i_X509_SIG.3 @@ -0,0 +1,33 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt D2I_X509_SIG 3 +.Os +.Sh NAME +.Nm d2i_X509_SIG , +.Nm i2d_X509_SIG +.Nd DigestInfo functions +.Sh SYNOPSIS +.In openssl/x509.h +.Ft X509_SIG * +.Fo d2i_X509_SIG +.Fa "X509_SIG **a" +.Fa "unsigned char **pp" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_X509_SIG +.Fa "X509_SIG *a" +.Fa "unsigned char **pp" +.Fc +.Sh DESCRIPTION +These functions decode and encode an +.Vt X509_SIG +structure which is equivalent to the +.Sy DigestInfo +structure defined in PKCS#1 and PKCS#7. +.Pp +Otherwise these behave in a way similar to +.Xr d2i_X509 3 +and +.Xr i2d_X509 3 . +.Sh SEE ALSO +.Xr d2i_X509 3 diff --git a/src/lib/libcrypto/man/x509.3 b/src/lib/libcrypto/man/x509.3 new file mode 100644 index 0000000000..1f7b7f4128 --- /dev/null +++ b/src/lib/libcrypto/man/x509.3 @@ -0,0 +1,79 @@ +.Dd $Mdocdate: November 4 2016 $ +.Dt X509 3 +.Os +.Sh NAME +.Nm x509 +.Nd X.509 certificate handling +.Sh SYNOPSIS +.In openssl/x509.h +.Sh DESCRIPTION +A X.509 certificate is a structured grouping of information about an +individual, a device, or anything one can imagine. +A X.509 CRL (certificate revocation list) is a tool to help determine if +a certificate is still valid. +The exact definition of those can be found in the X.509 document from +ITU-T, or in RFC3280 from PKIX. +In OpenSSL, the type +.Vt X509 +is used to express such a certificate, and the type +.Vt X509_CRL +is used to express a CRL. +.Pp +A related structure is a certificate request, defined in PKCS#10 from +RSA Security, Inc., also reflected in RFC2896. +In OpenSSL, the type +.Vt X509_REQ +is used to express such a certificate request. +.Pp +To handle some complex parts of a certificate, there are the types +.Vt X509_NAME +to express a certificate name, +.Vt X509_ATTRIBUTE +to express a certificate attribute, +.Vt X509_EXTENSION +to express a certificate extension, and a few more. +.Pp +Finally, there's the supertype +.Vt X509_INFO , +which can contain a CRL, a certificate, and a corresponding private key. +.Pp +The functions +.Fa X509_* , +.Fa d2i_X509_* , +and +.Fa i2d_X509_* +handle X.509 certificates, with some exceptions shown below. +.Pp +.Fa X509_CRL_* , +.Fa d2i_X509_CRL_* , +and +.Fa i2d_X509_CRL_* +handle X.509 CRLs. +.Pp +.Fa X509_REQ_* , +.Fa d2i_X509_REQ_* , +and +.Fa i2d_X509_REQ_* +handle PKCS#10 certificate requests. +.Pp +.Fa X509_NAME_* +handle certificate names. +.Pp +.Fa X509_ATTRIBUTE_* +handle certificate attributes. +.Pp +.Fa X509_EXTENSION_* +handle certificate extensions. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr d2i_X509 3 , +.Xr d2i_X509_ALGOR 3 , +.Xr d2i_X509_CRL 3 , +.Xr d2i_X509_NAME 3 , +.Xr d2i_X509_REQ 3 , +.Xr d2i_X509_SIG 3 , +.Xr X509_NAME_add_entry_by_NID 3 , +.Xr X509_NAME_add_entry_by_txt 3 , +.Xr X509_NAME_ENTRY_get_object 3 , +.Xr X509_NAME_new 3 , +.Xr X509_NAME_print_ex 3 -- cgit v1.2.3-55-g6feb