From aa4d426b4d3527d7e166df1a05058c9a4a0f6683 Mon Sep 17 00:00:00 2001 From: Wojtek Kosior Date: Fri, 30 Apr 2021 00:33:56 +0200 Subject: initial/final commit --- .../doc/crypto/X509_NAME_get_index_by_NID.pod | 123 +++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod (limited to 'openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod') diff --git a/openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod b/openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod new file mode 100644 index 0000000..2d6713b --- /dev/null +++ b/openssl-1.1.0h/doc/crypto/X509_NAME_get_index_by_NID.pod @@ -0,0 +1,123 @@ +=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, const ASN1_OBJECT *obj, int lastpos); + + int X509_NAME_entry_count(const X509_NAME *name); + X509_NAME_ENTRY *X509_NAME_get_entry(const 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, const 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. +If B 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. + +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. + +The list of all relevant B and B can be found in +the source code header files Eopenssl/obj_mac.hE and/or +Eopenssl/objects.hE. + +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: + + 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 lastpos = -1; + X509_NAME_ENTRY *e; + + 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_get_index_by_NID() can also return -2 if the supplied +NID is invalid. + +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 + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut -- cgit v1.2.3