aboutsummaryrefslogtreecommitdiff
path: root/openssl/doc
diff options
context:
space:
mode:
Diffstat (limited to 'openssl/doc')
-rw-r--r--openssl/doc/crypto/X509_NAME_get_index_by_NID.pod7
-rw-r--r--openssl/doc/crypto/X509_STORE_CTX_new.pod13
-rw-r--r--openssl/doc/crypto/X509_verify_cert.pod3
3 files changed, 18 insertions, 5 deletions
diff --git a/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod b/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod
index c8a812879..109f56132 100644
--- a/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod
+++ b/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod
@@ -29,6 +29,7 @@ and issuer names.
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve
the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>
should initially be set to -1. If there are no more entries -1 is returned.
+If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned.
X509_NAME_entry_count() returns the total number of entries in B<name>.
@@ -63,6 +64,10 @@ The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in
the source code header files E<lt>openssl/obj_mac.hE<gt> and/or
E<lt>openssl/objects.hE<gt>.
+Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
+should check for the return value of -2. Alternatively the NID validity
+can be determined first by checking OBJ_nid2obj(nid) is not NULL.
+
=head1 EXAMPLES
Process all entries:
@@ -95,6 +100,8 @@ Process all commonName entries:
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_get_index_by_NID() can also return -2 if the supplied
+NID is invalid.
X509_NAME_entry_count() returns the total number of entries.
diff --git a/openssl/doc/crypto/X509_STORE_CTX_new.pod b/openssl/doc/crypto/X509_STORE_CTX_new.pod
index b17888f14..eb38b0a10 100644
--- a/openssl/doc/crypto/X509_STORE_CTX_new.pod
+++ b/openssl/doc/crypto/X509_STORE_CTX_new.pod
@@ -39,10 +39,15 @@ X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx>
is no longer valid.
X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation.
-The trusted certificate store is set to B<store>, the end entity certificate
-to be verified is set to B<x509> and a set of additional certificates (which
-will be untrusted but may be used to build the chain) in B<chain>. Any or
-all of the B<store>, B<x509> and B<chain> parameters can be B<NULL>.
+It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only
+good for one call to X509_verify_cert(); if you want to verify a second
+certificate with the same B<ctx> then you must call X509_XTORE_CTX_cleanup()
+and then X509_STORE_CTX_init() again before the second call to
+X509_verify_cert(). The trusted certificate store is set to B<store>, the end
+entity certificate to be verified is set to B<x509> and a set of additional
+certificates (which will be untrusted but may be used to build the chain) in
+B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be
+B<NULL>.
X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B<ctx>
to B<sk>. This is an alternative way of specifying trusted certificates
diff --git a/openssl/doc/crypto/X509_verify_cert.pod b/openssl/doc/crypto/X509_verify_cert.pod
index 5253bdcd7..a22e44118 100644
--- a/openssl/doc/crypto/X509_verify_cert.pod
+++ b/openssl/doc/crypto/X509_verify_cert.pod
@@ -32,7 +32,8 @@ 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<ctx> (due to a programming error) or if a retry
+certificate is set in B<ctx> (due to a programming error); if X509_verify_cert()
+twice without reinitialising B<ctx> in between; 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.