convert remaining ASN1 object manuals from pod to mdoc

5 files changed, 299 insertions, 175 deletions

diff --git a/src/lib/libcrypto/doc/OBJ_nid2obj.pod b/src/lib/libcrypto/doc/OBJ_nid2obj.pod
deleted file mode 100644
index 95949ac091..0000000000
--- a/src/lib/libcrypto/doc/OBJ_nid2obj.pod
+++ /dev/null
@@ -1,147 +0,0 @@
-=pod
-
-=head1 NAME
-
-OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid,
-OBJ_sn2nid, OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup
-- ASN1 object utility functions
-
-=head1 SYNOPSIS
-
- #include <openssl/objects.h>
-
- ASN1_OBJECT * OBJ_nid2obj(int n);
- const char *  OBJ_nid2ln(int n);
- const char *  OBJ_nid2sn(int n);
-
- int OBJ_obj2nid(const ASN1_OBJECT *o);
- int OBJ_ln2nid(const char *ln);
- int OBJ_sn2nid(const char *sn);
-
- int OBJ_txt2nid(const char *s);
-
- ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name);
- int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name);
-
- int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b);
- ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);
-
- int OBJ_create(const char *oid,const char *sn,const char *ln);
- void OBJ_cleanup(void);
-
-=head1 DESCRIPTION
-
-The ASN1 object utility functions process ASN1_OBJECT structures which are
-a representation of the ASN1 OBJECT IDENTIFIER (OID) type.
-
-OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to
-an ASN1_OBJECT structure, its long name and its short name respectively,
-or B<NULL> is an error occurred.
-
-OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID
-for the object B<o>, the long name <ln> or the short name <sn> respectively
-or NID_undef if an error occurred.
-
-OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
-a long name, a short name or the numerical representation of an object.
-
-OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
-If B<no_name> is 0 then long names and short names will be interpreted
-as well as numerical forms. If B<no_name> is 1 only the numerical form
-is acceptable.
-
-OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation.
-The representation is written as a null terminated string to B<buf>
-at most B<buf_len> bytes are written, truncating the result if necessary.
-The total amount of space required is returned. If B<no_name> is 0 then
-if the object has a long or short name then that will be used, otherwise
-the numerical form will be used. If B<no_name> is 1 then the numerical
-form will always be used.
-
-OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned.
-
-OBJ_dup() returns a copy of B<o>.
-
-OBJ_create() adds a new object to the internal table. B<oid> is the
-numerical form of the object, B<sn> the short name and B<ln> the
-long name. A new NID is returned for the created object.
-
-OBJ_cleanup() cleans up OpenSSLs internal object table: this should
-be called before an application exits if any new objects were added
-using OBJ_create().
-
-=head1 NOTES
-
-Objects in OpenSSL can have a short name, a long name and a numerical
-identifier (NID) associated with them. A standard set of objects is
-represented in an internal table. The appropriate values are defined
-in the header file B<objects.h>.
-
-For example the OID for commonName has the following definitions:
-
- #define SN_commonName                   "CN"
- #define LN_commonName                   "commonName"
- #define NID_commonName                  13
-
-New objects can be added by calling OBJ_create().
-
-Table objects have certain advantages over other objects: for example
-their NIDs can be used in a C language switch statement. They are
-also static constant structures which are shared: that is there
-is only a single constant structure for each table object.
-
-Objects which are not in the table have the NID value NID_undef.
-
-Objects do not need to be in the internal tables to be processed,
-the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical
-form of an OID.
-
-=head1 EXAMPLES
-
-Create an object for B<commonName>:
-
- ASN1_OBJECT *o;
- o = OBJ_nid2obj(NID_commonName);
-
-Check if an object is B<commonName>
-
- if (OBJ_obj2nid(obj) == NID_commonName)
-        /* Do something */
-
-Create a new NID and initialize an object from it:
-
- int new_nid;
- ASN1_OBJECT *obj;
- new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
-
- obj = OBJ_nid2obj(new_nid);
-
-Create a new object directly:
-
- obj = OBJ_txt2obj("1.2.3.4", 1);
-
-=head1 BUGS
-
-OBJ_obj2txt() is awkward and messy to use: it doesn't follow the
-convention of other OpenSSL functions where the buffer can be set
-to B<NULL> to determine the amount of data that should be written.
-Instead B<buf> must point to a valid buffer and B<buf_len> should
-be set to a positive value. A buffer length of 80 should be more
-than enough to handle any OID encountered in practice.
-
-=head1 RETURN VALUES
-
-OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
-error occurred.
-
-OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
-on error.
-
-OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
-a NID or B<NID_undef> on error.
-
-=head1 SEE ALSO
-
-L<ERR_get_error(3)|ERR_get_error(3)>
-
-=cut
diff --git a/src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod b/src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod
deleted file mode 100644
index b2712dc55c..0000000000
--- a/src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod
+++ /dev/null
@@ -1,25 +0,0 @@
-=pod
-
-=head1 NAME
-
-d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions
-
-=head1 SYNOPSIS
-
- #include <openssl/objects.h>
-
- ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length);
- int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp);
-
-=head1 DESCRIPTION
-
-These functions decode and encode an ASN1 OBJECT IDENTIFIER.
-
-Othewise these behave in a similar way to d2i_X509() and i2d_X509()
-described in the L<d2i_X509(3)|d2i_X509(3)> manual page.
-
-=head1 SEE ALSO
-
-L<d2i_X509(3)|d2i_X509(3)>
-
-=cut
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 1989a25092..802b34399f 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.39 2016/11/03 10:02:57 schwarze Exp $
+# $OpenBSD: Makefile,v 1.40 2016/11/03 10:24:26 schwarze Exp $
 
 .include <bsd.own.mk>           # for NOMAN
 
@@ -117,16 +117,17 @@ MAN=	\
         EVP_VerifyInit.3 \
         HMAC.3 \
         MD5.3 \
+        OBJ_nid2obj.3 \
         UI_new.3 \
         bn_dump.3 \
         crypto.3 \
+        d2i_ASN1_OBJECT.3 \
         d2i_PKCS8PrivateKey_bio.3 \
         des_read_pw.3 \
         evp.3 \
         lh_new.3 \
 
 GENMAN= \
-        OBJ_nid2obj.3 \
         OPENSSL_VERSION_NUMBER.3 \
         OPENSSL_config.3 \
         OPENSSL_load_builtin_modules.3 \
@@ -178,7 +179,6 @@ GENMAN= \
         X509_new.3 \
         X509_verify_cert.3 \
         bn.3 \
-        d2i_ASN1_OBJECT.3 \
         d2i_DHparams.3 \
         d2i_DSAPublicKey.3 \
         d2i_ECPKParameters.3 \
diff --git a/src/lib/libcrypto/man/OBJ_nid2obj.3 b/src/lib/libcrypto/man/OBJ_nid2obj.3
new file mode 100644
index 0000000000..5634d8ea4a
--- /dev/null
+++ b/src/lib/libcrypto/man/OBJ_nid2obj.3
@@ -0,0 +1,267 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt OBJ_NID2OBJ 3
+.Os
+.Sh NAME
+.Nm OBJ_nid2obj ,
+.Nm OBJ_nid2ln ,
+.Nm OBJ_nid2sn ,
+.Nm OBJ_obj2nid ,
+.Nm OBJ_txt2nid ,
+.Nm OBJ_ln2nid ,
+.Nm OBJ_sn2nid ,
+.Nm OBJ_cmp ,
+.Nm OBJ_dup ,
+.Nm OBJ_txt2obj ,
+.Nm OBJ_obj2txt ,
+.Nm OBJ_create ,
+.Nm OBJ_cleanup
+.Nd ASN1 object utility functions
+.Sh SYNOPSIS
+.In openssl/objects.h
+.Ft ASN1_OBJECT *
+.Fo OBJ_nid2obj
+.Fa "int n"
+.Fc
+.Ft const char *
+.Fo OBJ_nid2ln
+.Fa "int n"
+.Fc
+.Ft const char *
+.Fo OBJ_nid2sn
+.Fa "int n"
+.Fc
+.Ft int
+.Fo OBJ_obj2nid
+.Fa "const ASN1_OBJECT *o"
+.Fc
+.Ft int
+.Fo OBJ_ln2nid
+.Fa "const char *ln"
+.Fc
+.Ft int
+.Fo OBJ_sn2nid
+.Fa "const char *sn"
+.Fc
+.Ft int
+.Fo OBJ_txt2nid
+.Fa "const char *s"
+.Fc
+.Ft ASN1_OBJECT *
+.Fo OBJ_txt2obj
+.Fa "const char *s"
+.Fa "int no_name"
+.Fc
+.Ft int
+.Fo OBJ_obj2txt
+.Fa "char *buf"
+.Fa "int buf_len"
+.Fa "const ASN1_OBJECT *a"
+.Fa "int no_name"
+.Fc
+.Ft int
+.Fo OBJ_cmp
+.Fa "const ASN1_OBJECT *a"
+.Fa "const ASN1_OBJECT *b"
+.Fc
+.Ft ASN1_OBJECT *
+.Fo OBJ_dup
+.Fa "const ASN1_OBJECT *o"
+.Fc
+.Ft int
+.Fo OBJ_create
+.Fa "const char *oid"
+.Fa "const char *sn"
+.Fa "const char *ln"
+.Fc
+.Ft void
+.Fn OBJ_cleanup void
+.Sh DESCRIPTION
+The ASN1 object utility functions process
+.Vt ASN1_OBJECT
+structures which are a representation of the ASN1 OBJECT IDENTIFIER
+(OID) type.
+.Pp
+.Fn OBJ_nid2obj ,
+.Fn OBJ_nid2ln ,
+and
+.Fn OBJ_nid2sn
+convert the NID
+.Fa n
+to an
+.Vt ASN1_OBJECT
+structure, its long name, and its short name, respectively, or return
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn OBJ_obj2nid ,
+.Fn OBJ_ln2nid ,
+and
+.Fn OBJ_sn2nid
+return the corresponding NID for the object
+.Fa o ,
+the long name
+.Fa ln ,
+or the short name
+.Fa sn ,
+respectively, or
+.Dv NID_undef
+if an error occurred.
+.Pp
+.Fn OBJ_txt2nid
+returns the NID corresponding to text string
+.Fa s .
+.Fa s
+can be a long name, a short name, or the numerical representation
+of an object.
+.Pp
+.Fn OBJ_txt2obj
+converts the text string
+.Fa s
+into an
+.Vt ASN1_OBJECT
+structure.
+If
+.Fa no_name
+is 0 then long names and short names will be interpreted as well as
+numerical forms.
+If
+.Fa no_name
+is 1 only the numerical form is acceptable.
+.Pp
+.Fn OBJ_obj2txt
+converts the
+.Vt ASN1_OBJECT
+.Fa a
+into a textual representation.
+The representation is written as a NUL terminated string to
+.Fa buf .
+At most
+.Fa buf_len
+bytes are written, truncating the result if necessary.
+The total amount of space required is returned.
+If
+.Fa no_name
+is 0 and the object has a long or short name, then that will be used,
+otherwise the numerical form will be used.
+.Pp
+.Fn OBJ_cmp
+compares
+.Fa a
+to
+.Fa b .
+If the two are identical, 0 is returned.
+.Pp
+.Fn OBJ_dup
+returns a copy of
+.Fa o .
+.Pp
+.Fn OBJ_create
+adds a new object to the internal table.
+.Fa oid
+is the numerical form of the object,
+.Fa sn
+the short name and
+.Fa ln
+the long name.
+A new NID is returned for the created object.
+.Pp
+.Fn OBJ_cleanup
+cleans up the internal object table: this should be called before
+an application exits if any new objects were added using
+.Fn OBJ_create .
+.Pp
+Objects can have a short name, a long name, and a numerical
+identifier (NID) associated with them.
+A standard set of objects is represented in an internal table.
+The appropriate values are defined in the header file
+.In openssl/objects.h .
+.Pp
+For example, the OID for commonName has the following definitions:
+.Bd -literal
+#define SN_commonName                   "CN"
+#define LN_commonName                   "commonName"
+#define NID_commonName                  13
+.Ed
+.Pp
+New objects can be added by calling
+.Fn OBJ_create .
+.Pp
+Table objects have certain advantages over other objects: for example
+their NIDs can be used in a C language switch statement.
+They are also static constant structures which are shared: that is there
+is only a single constant structure for each table object.
+.Pp
+Objects which are not in the table have the NID value
+.Dv NID_undef .
+.Pp
+Objects do not need to be in the internal tables to be processed, the
+functions
+.Fn OBJ_txt2obj
+and
+.Fn OBJ_obj2txt
+can process the numerical form of an OID.
+.Sh RETURN VALUES
+.Fn OBJ_nid2obj
+returns an
+.Vt ASN1_OBJECT
+structure or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn OBJ_nid2ln
+and
+.Fn OBJ_nid2sn
+returns a valid string or
+.Dv NULL
+on error.
+.Pp
+.Fn OBJ_obj2nid ,
+.Fn OBJ_ln2nid ,
+.Fn OBJ_sn2nid ,
+and
+.Fn OBJ_txt2nid
+return a NID or
+.Dv NID_undef
+on error.
+.Sh EXAMPLES
+Create an object for
+.Sy commonName :
+.Bd -literal
+ASN1_OBJECT *o;
+o = OBJ_nid2obj(NID_commonName);
+.Ed
+.Pp
+Check if an object is
+.Sy commonName
+.Bd -literal
+if (OBJ_obj2nid(obj) == NID_commonName)
+        /* Do something */
+.Ed
+.Pp
+Create a new NID and initialize an object from it:
+.Bd -literal
+int new_nid;
+ASN1_OBJECT *obj;
+new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier");
+obj = OBJ_nid2obj(new_nid);
+.Ed
+.Pp
+Create a new object directly:
+.Bd -literal
+obj = OBJ_txt2obj("1.2.3.4", 1);
+.Ed
+.Sh SEE ALSO
+.Xr ERR_get_error 3
+.Sh BUGS
+.Fn OBJ_obj2txt
+is awkward and messy to use: it doesn't follow the convention of other
+OpenSSL functions where the buffer can be set to
+.Dv NULL
+to determine the amount of data that should be written.
+Instead
+.Fa buf
+must point to a valid buffer and
+.Fa buf_len
+should be set to a positive value.
+A buffer length of 80 should be more than enough to handle any OID
+encountered in practice.
diff --git a/src/lib/libcrypto/man/d2i_ASN1_OBJECT.3 b/src/lib/libcrypto/man/d2i_ASN1_OBJECT.3
new file mode 100644
index 0000000000..686101cff5
--- /dev/null
+++ b/src/lib/libcrypto/man/d2i_ASN1_OBJECT.3
@@ -0,0 +1,29 @@
+.Dd $Mdocdate: November 3 2016 $
+.Dt D2I_ASN1_OBJECT 3
+.Os
+.Sh NAME
+.Nm d2i_ASN1_OBJECT ,
+.Nm i2d_ASN1_OBJECT
+.Nd ASN1 OBJECT IDENTIFIER functions
+.Sh SYNOPSIS
+.In openssl/objects.h
+.Ft ASN1_OBJECT *
+.Fo d2i_ASN1_OBJECT
+.Fa "ASN1_OBJECT **a"
+.Fa "unsigned char **pp"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_OBJECT
+.Fa "ASN1_OBJECT *a"
+.Fa "unsigned char **pp"
+.Fc
+.Sh DESCRIPTION
+These functions decode and encode an ASN1 OBJECT IDENTIFIER.
+.Pp
+Otherwise these behave in a similar way to
+.Xr d2i_X509 3
+and
+.Xr i2d_X509 3 .
+.Sh SEE ALSO
+.Xr d2i_X509 3