Document d2i_ASN1_TYPE(3) and i2d_ASN1_TYPE(3),

both listed in <openssl/asn1.h> and in OpenSSL doc/man3/d2i_X509.pod.
Minor wording improvements while here.

1 files changed, 46 insertions, 9 deletions

diff --git a/src/lib/libcrypto/man/ASN1_item_d2i.3 b/src/lib/libcrypto/man/ASN1_item_d2i.3
index afdd234c23..4bdaf4bad4 100644
--- a/src/lib/libcrypto/man/ASN1_item_d2i.3
+++ b/src/lib/libcrypto/man/ASN1_item_d2i.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ASN1_item_d2i.3,v 1.3 2016/12/27 08:20:27 jmc Exp $
+.\"     $OpenBSD: ASN1_item_d2i.3,v 1.4 2017/01/03 23:56:50 schwarze Exp $
 .\"     OpenSSL doc/man3/d2i_X509.pod b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file is a derived work.
@@ -65,16 +65,18 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 27 2016 $
+.Dd $Mdocdate: January 3 2017 $
 .Dt ASN1_ITEM_D2I 3
 .Os
 .Sh NAME
 .Nm ASN1_item_d2i ,
 .Nm ASN1_item_d2i_bio ,
 .Nm ASN1_item_d2i_fp ,
+.Nm d2i_ASN1_TYPE ,
 .Nm ASN1_item_i2d ,
 .Nm ASN1_item_i2d_bio ,
 .Nm ASN1_item_i2d_fp ,
+.Nm i2d_ASN1_TYPE ,
 .Nm ASN1_item_dup ,
 .Nm ASN1_item_print
 .Nd decode and encode ASN.1 objects
@@ -99,6 +101,12 @@
 .Fa "FILE *in_fp"
 .Fa "void *val_out"
 .Fc
+.Ft ASN1_TYPE *
+.Fo d2i_ASN1_TYPE
+.Fa "ASN1_TYPE **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
 .Ft int
 .Fo ASN1_item_i2d
 .Fa "ASN1_VALUE *val_in"
@@ -117,6 +125,11 @@
 .Fa "FILE *out_fp"
 .Fa "void *val_in"
 .Fc
+.Ft int
+.Fo i2d_ASN1_TYPE
+.Fa "ASN1_TYPE *val_in"
+.Fa "unsigned char **der_out"
+.Fc
 .Ft void *
 .Fo ASN1_item_dup
 .Fa "const ASN1_ITEM *it"
@@ -131,19 +144,21 @@
 .Fa "const ASN1_PCTX *pctx"
 .Fc
 .Sh DESCRIPTION
-These functions convert ASN.1 values from their DER encoding to
+These functions convert ASN.1 values from their BER encoding to
 internal C structures
 .Pq Dq d2i
 and vice versa
 .Pq Dq i2d .
-Unlike the C structures which contain pointers to sub-objects, DER
+Unlike the C structures which contain pointers to sub-objects, BER
 is a serialized encoding, suitable for transfer over the network
 and for storage in a file.
 .Pp
 .Fn ASN1_item_d2i
 interpretes
 .Pf * Fa der_in
-as a DER- or BER-encoded byte array and decodes
+as a DER- or BER-encoded byte array and decodes one value of type
+.Fa it
+represented by up to
 .Fa length
 bytes.
 If successful,
@@ -187,6 +202,14 @@ or
 .Vt FILE ,
 respectively.
 .Pp
+.Fn d2i_ASN1_TYPE
+is similar to
+.Fn ASN1_item_d2i
+except that it does not require a desired type to be specified by
+the user, but instead returns an
+.Vt ASN1_TYPE
+wrapper object containing both the type and the value found in the input.
+.Pp
 .Fn ASN1_item_i2d
 encodes the object pointed to by
 .Fa val_in
@@ -239,6 +262,14 @@ or
 .Vt FILE ,
 respectively.
 .Pp
+.Fn i2d_ASN1_TYPE
+is similar to
+.Fn ASN1_item_i2d
+except that the type and the value are not provided separately,
+but in the form of a single
+.Vt ASN1_TYPE
+object.
+.Pp
 .Fn ASN1_item_dup
 creates a deep copy of
 .Fa val_in
@@ -250,8 +281,9 @@ and
 If successful,
 .Fn ASN1_item_d2i ,
 .Fn ASN1_item_d2i_bio ,
+.Fn ASN1_item_d2i_fp ,
 and
-.Fn ASN1_item_d2i_fp
+.Fn d2i_ASN1_TYPE
 return a pointer to the decoded ASN.1 value.
 In addition, if
 .Fa val_out
@@ -264,7 +296,9 @@ If an error occurs,
 is returned.
 .Pp
 .Fn ASN1_item_i2d
-returns the number of bytes written
+and
+.Fn i2d_ASN1_TYPE
+return the number of bytes written
 or a negative value if an error occurs.
 .Pp
 .Fn ASN1_item_i2d_bio
@@ -282,7 +316,9 @@ if an error occurs.
 Many type-specific wrapper functions exist.
 Using those wrappers is recommended in application code
 because it restores part of the type safety that the low-level
-interfaces described in the present manual page lack.
+interfaces using
+.Vt ASN1_VALUE
+lack.
 .Pp
 For example, to allocate a buffer and write the DER encoding of an
 .Vt X509
@@ -325,7 +361,8 @@ if (d2i_X509(&x, &p, len) == NULL)
         /* error */
 .Ed
 .Sh SEE ALSO
-.Xr ASN1_item_new 3
+.Xr ASN1_item_new 3 ,
+.Xr ASN1_TYPE_new 3
 .Sh CAVEATS
 If the type described by
 .Fa it