[openssl-commits] [openssl] master update
Dr. Stephen Henson
steve at openssl.org
Sat Dec 12 14:16:31 UTC 2015
The branch master has been updated
via 9391ba1b51fac77a1255f3d9a0d275e4cce9d543 (commit)
via 3a59ad98e986b928f853d6ff740fc28ef34657d0 (commit)
via e989e54f66a86aca816fc15c2e9edccc3c542547 (commit)
from a5ecdc6af8f36d034ede991c8524b70d9ee72be6 (commit)
- Log -----------------------------------------------------------------
commit 9391ba1b51fac77a1255f3d9a0d275e4cce9d543
Author: Dr. Stephen Henson <steve at openssl.org>
Date: Fri Dec 11 02:59:10 2015 +0000
Add extension utility documentation.
Reviewed-by: Kurt Roeckx <kurt at openssl.org>
commit 3a59ad98e986b928f853d6ff740fc28ef34657d0
Author: Dr. Stephen Henson <steve at openssl.org>
Date: Fri Dec 11 00:36:06 2015 +0000
add X509_up_ref() documentation
Reviewed-by: Kurt Roeckx <kurt at openssl.org>
commit e989e54f66a86aca816fc15c2e9edccc3c542547
Author: Dr. Stephen Henson <steve at openssl.org>
Date: Thu Dec 10 19:13:57 2015 +0000
extension documentation
Reviewed-by: Kurt Roeckx <kurt at openssl.org>
-----------------------------------------------------------------------
Summary of changes:
doc/crypto/X509_EXTENSION_set_object.pod | 83 ++++++++++++++++++
doc/crypto/X509_new.pod | 20 +++--
doc/crypto/X509v3_get_ext_by_NID.pod | 142 +++++++++++++++++++++++++++++++
3 files changed, 240 insertions(+), 5 deletions(-)
create mode 100644 doc/crypto/X509_EXTENSION_set_object.pod
create mode 100644 doc/crypto/X509v3_get_ext_by_NID.pod
diff --git a/doc/crypto/X509_EXTENSION_set_object.pod b/doc/crypto/X509_EXTENSION_set_object.pod
new file mode 100644
index 0000000..6afef2b
--- /dev/null
+++ b/doc/crypto/X509_EXTENSION_set_object.pod
@@ -0,0 +1,83 @@
+=head1 NAME
+
+X509_EXTENSION_set_object, X509_EXTENSION_set_critical,
+X509_EXTENSION_set_data, X509_EXTENSION_create_by_NID,
+X509_EXTENSION_create_by_OBJ, X509_EXTENSION_get_object,
+X509_EXTENSION_get_critical, X509_EXTENSION_get_data - extension utility
+functions.
+
+=head1 SYNOPSIS
+
+ int X509_EXTENSION_set_object(X509_EXTENSION *ex, ASN1_OBJECT *obj);
+ int X509_EXTENSION_set_critical(X509_EXTENSION *ex, int crit);
+ int X509_EXTENSION_set_data(X509_EXTENSION *ex, ASN1_OCTET_STRING *data);
+
+ X509_EXTENSION *X509_EXTENSION_create_by_NID(X509_EXTENSION **ex,
+ int nid, int crit,
+ ASN1_OCTET_STRING *data);
+ X509_EXTENSION *X509_EXTENSION_create_by_OBJ(X509_EXTENSION **ex,
+ ASN1_OBJECT *obj, int crit,
+ ASN1_OCTET_STRING *data);
+
+ ASN1_OBJECT *X509_EXTENSION_get_object(X509_EXTENSION *ex);
+ int X509_EXTENSION_get_critical(X509_EXTENSION *ex);
+ ASN1_OCTET_STRING *X509_EXTENSION_get_data(X509_EXTENSION *ne);
+
+=head1 DESCRIPTION
+
+X509_EXTENSION_set_object() sets the extension type of B<ex> to B<obj>. The
+B<obj> pointer is duplicated internally so B<obj> should be freed up after use.
+
+X509_EXTENSION_set_critical() sets the criticality of B<ex> to B<crit>. If
+B<crit> is zero the extension in non-critical otherwise it is critical.
+
+X509_EXTENSION_set_data() sets the data in extension B<ex> to B<data>. The
+B<data> pointer is duplicated internally.
+
+X509_EXTENSION_create_by_NID() creates an extension of type B<nid>,
+criticality B<crit> using data B<data>. The created extension is returned and
+written to B<*ex> reusing or allocating a new extension if necessary so B<*ex>
+should either be B<NULL> or a valid B<X509_EXTENSION> structure it must
+B<not> be an uninitialised pointer.
+
+X509_EXTENSION_create_by_OBJ() is identical to X509_EXTENSION_create_by_NID()
+except it creates and extension using B<obj> instead of a NID.
+
+X509_EXTENSION_get_object() returns the extension type of B<ex> as an
+B<ASN1_OBJECT> pointer. The returned pointer is an internal value which must
+not be freed up.
+
+X509_EXTENSION_get_critical() returns the criticality of extension B<ex> it
+returns B<1> for critical and B<0> for non-critical.
+
+X509_EXTENSION_get_data() returns the data of extension B<ex>. The returned
+pointer is an internal value which must not be freed up.
+
+=head1 NOTES
+
+These functions manipulate the contents of an extension directly. Most
+applications will want to parse or encode and add an extension: they should
+use the extension encode and decode functions instead such as
+X509_add1_ext_i2d() and X509_get_ext_d2i().
+
+The B<data> associated with an extension is the extension encoding in an
+B<ASN1_OCTET_STRING> structure.
+
+=head1 RETURN VALUES
+
+X509_EXTENSION_set_object() X509_EXTENSION_set_critical() and
+X509_EXTENSION_set_data() return B<1> for success and B<0> for failure.
+
+X509_EXTENSION_create_by_NID() and X509_EXTENSION_create_by_OBJ() return
+an B<X509_EXTENSION> pointer or B<NULL> if an error occurs.
+
+X509_EXTENSION_get_object() returns an B<ASN1_OBJECT> pointer.
+
+X509_EXTENSION_get_critical() returns B<0> for non-critical and B<1> for
+critical.
+
+X509_EXTENSION_get_data() returns an B<ASN1_OCTET_STRING> pointer.
+
+=head1 SEE ALSO
+
+L<X509V3_get_d2i(3)>
diff --git a/doc/crypto/X509_new.pod b/doc/crypto/X509_new.pod
index 8e2ac98..d6c365f 100644
--- a/doc/crypto/X509_new.pod
+++ b/doc/crypto/X509_new.pod
@@ -2,7 +2,7 @@
=head1 NAME
-X509_new, X509_free - X509 certificate ASN1 allocation functions
+X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions
=head1 SYNOPSIS
@@ -10,16 +10,26 @@ X509_new, X509_free - X509 certificate ASN1 allocation functions
X509 *X509_new(void);
void X509_free(X509 *a);
+ void X509_up_ref(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_new() allocates and initializes a X509 structure with reference count
+B<1>.
-X509_free() frees up the B<X509> structure B<a>.
-If B<a> is NULL nothing is done.
+X509_free() decrements the reference count of B<X509> structure B<a> and
+frees it up if the reference count is zero. If B<a> is NULL nothing is done.
+
+X509_up_ref() increments the reference count of B<a>.
+
+=head1 NOTES
+
+The function X509_up_ref() if useful if a certificate structure is being
+used by several different operations each of which will free it up after
+use: this avoids the need to duplicate the entire certificate structure.
=head1 RETURN VALUES
@@ -27,7 +37,7 @@ If the allocation fails, X509_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
-X509_free() returns no value.
+X509_free() and X509_up_ref() do not return a value.
=head1 SEE ALSO
diff --git a/doc/crypto/X509v3_get_ext_by_NID.pod b/doc/crypto/X509v3_get_ext_by_NID.pod
new file mode 100644
index 0000000..b11d663
--- /dev/null
+++ b/doc/crypto/X509v3_get_ext_by_NID.pod
@@ -0,0 +1,142 @@
+=pod
+
+=head1 NAME
+
+X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID,
+X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext,
+X509v3_add_ext, X509_get0_extensions, X509_CRL_get0_extensions,
+X509_REVOKED_get0_extensions, X509_get_ext_count, X509_get_ext,
+X509_get_ext_by_NID, X509_get_ext_by_OBJ, X509_get_ext_by_critical,
+X509_delete_ext, X509_add_ext, X509_CRL_get_ext_count, X509_CRL_get_ext,
+X509_CRL_get_ext_by_NID, X509_CRL_get_ext_by_OBJ, X509_CRL_get_ext_by_critical,
+X509_CRL_delete_ext, X509_CRL_add_ext, X509_REVOKED_get_ext_count,
+X509_REVOKED_get_ext, X509_REVOKED_get_ext_by_NID, X509_REVOKED_get_ext_by_OBJ,
+X509_REVOKED_get_ext_by_critical, X509_REVOKED_delete_ext,
+X509_REVOKED_add_ext - extension stack utility functions.
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509.h>
+
+ int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x);
+ X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc);
+
+ int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x,
+ int nid, int lastpos);
+ int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x,
+ ASN1_OBJECT *obj, int lastpos);
+ int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x,
+ int crit, int lastpos);
+ X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc);
+ STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x,
+ X509_EXTENSION *ex, int loc);
+
+ STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
+ STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(X509_CRL *crl);
+ STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(X509_REVOKED *r);
+
+ int X509_get_ext_count(X509 *x);
+ X509_EXTENSION *X509_get_ext(X509 *x, int loc);
+ int X509_get_ext_by_NID(X509 *x, int nid, int lastpos);
+ int X509_get_ext_by_OBJ(X509 *x, ASN1_OBJECT *obj, int lastpos);
+ int X509_get_ext_by_critical(X509 *x, int crit, int lastpos);
+ X509_EXTENSION *X509_delete_ext(X509 *x, int loc);
+ int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc);
+
+ int X509_CRL_get_ext_count(X509_CRL *x);
+ X509_EXTENSION *X509_CRL_get_ext(X509_CRL *x, int loc);
+ int X509_CRL_get_ext_by_NID(X509_CRL *x, int nid, int lastpos);
+ int X509_CRL_get_ext_by_OBJ(X509_CRL *x, ASN1_OBJECT *obj, int lastpos);
+ int X509_CRL_get_ext_by_critical(X509_CRL *x, int crit, int lastpos);
+ X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc);
+ int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc);
+
+ int X509_REVOKED_get_ext_count(X509_REVOKED *x);
+ X509_EXTENSION *X509_REVOKED_get_ext(X509_REVOKED *x, int loc);
+ int X509_REVOKED_get_ext_by_NID(X509_REVOKED *x, int nid, int lastpos);
+ int X509_REVOKED_get_ext_by_OBJ(X509_REVOKED *x, ASN1_OBJECT *obj,
+ int lastpos);
+ int X509_REVOKED_get_ext_by_critical(X509_REVOKED *x, int crit, int lastpos);
+ X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc);
+ int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc);
+
+=head1 DESCRIPTION
+
+X509v3_get_ext_count() retrieves the number of extensions in B<x>.
+
+X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc>
+can take any value from B<0> to X509_get_ext_count(x) - 1. The returned
+extension is an internal pointer which B<must not> be freed up by the
+application.
+
+X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension
+with B<nid> or B<obj> from extension stack B<x>. The search starts from the
+extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If
+the extension is found its index is returned otherwise B<-1> is returned.
+
+X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it
+looks for an extension of criticality B<crit>. A zero value for B<crit>
+looks for a non-critical extension a non-zero value looks for a critical
+extension.
+
+X509v3_delete_ext() deletes the extension with index B<loc> from B<x>. The
+deleted extension is returned and must be freed by the caller. If B<loc>
+is in invalid index value B<NULL> is returned.
+
+X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If
+B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL>
+a new stack will be allocated. The passed extension B<ex> is duplicated
+internally so it must be freed after use.
+
+X509_get0_extensions(), X509_CRL_get0_extensions() and
+X509_REVOKED_get0_extensions() retrieve the extensions from a certificate
+a CRL or a CRL entry respectively.
+
+X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(),
+X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext()
+and X509_add_ext() operate on the extensions of certificate B<x> they are
+otherwise identical to the X509v3 functions.
+
+X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(),
+X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(),
+X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of
+CRL B<x> they are otherwise identical to the X509v3 functions.
+
+X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(),
+X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(),
+X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and
+X509_REVOKED_add_ext() operate on the extensions of CRL entry B<x>
+they are otherwise identical to the X509v3 functions.
+
+=head1 NOTES
+
+These functions are used to examine stacks of extensions directly. Many
+applications will want to parse or encode and add an extension: they should
+use the extension encode and decode functions instead such as
+X509_add1_ext_i2d() and X509_get_ext_d2i().
+
+Extension indices start from zero, so a zero index return value is B<not> an
+error. These search functions start from the extension B<after> the B<lastpos>
+parameter so it should initially be set to B<-1>, if it is set to zero the
+initial extension will not be checked.
+
+=head1 RETURN VALUES
+
+X509v3_get_ext_count() returns the extension count.
+
+X509v3_get_ext() and X509v3_delete_ext() return an B<X509_EXTENSION> pointer
+or B<NULL> if an error occurs.
+
+X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and
+X509v3_get_ext_by_critical() return the an extension index or B<-1> if an
+error occurs.
+
+X509v3_add_ext() returns a stack of extensions or B<NULL> on error.
+
+X509_get0_extensions(), X509_CRL_get0_extensions() and
+X509_REVOKED_get0_extensions() return a stack of extensions. If the extensions
+field is absent it will return B<NULL>: this is B<not> an error condition.
+
+=head1 SEE ALSO
+
+L<X509V3_get_d2i(3)>
More information about the openssl-commits
mailing list