From 99421a4d33ceb28652f51f4a28160d96485e712e Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 3 Nov 2016 10:24:26 +0000 Subject: convert remaining ASN1 object manuals from pod to mdoc --- src/lib/libcrypto/doc/OBJ_nid2obj.pod | 147 ---------------- src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod | 25 --- src/lib/libcrypto/man/Makefile | 6 +- src/lib/libcrypto/man/OBJ_nid2obj.3 | 267 ++++++++++++++++++++++++++++++ src/lib/libcrypto/man/d2i_ASN1_OBJECT.3 | 29 ++++ 5 files changed, 299 insertions(+), 175 deletions(-) delete mode 100644 src/lib/libcrypto/doc/OBJ_nid2obj.pod delete mode 100644 src/lib/libcrypto/doc/d2i_ASN1_OBJECT.pod create mode 100644 src/lib/libcrypto/man/OBJ_nid2obj.3 create mode 100644 src/lib/libcrypto/man/d2i_ASN1_OBJECT.3 (limited to 'src') 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 - - 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 to -an ASN1_OBJECT structure, its long name and its short name respectively, -or B is an error occurred. - -OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() return the corresponding NID -for the object B, the long name or the short name respectively -or NID_undef if an error occurred. - -OBJ_txt2nid() returns NID corresponding to text string . B can be -a long name, a short name or the numerical representation of an object. - -OBJ_txt2obj() converts the text string B into an ASN1_OBJECT structure. -If B is 0 then long names and short names will be interpreted -as well as numerical forms. If B is 1 only the numerical form -is acceptable. - -OBJ_obj2txt() converts the B B into a textual representation. -The representation is written as a null terminated string to B -at most B bytes are written, truncating the result if necessary. -The total amount of space required is returned. If B 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 is 1 then the numerical -form will always be used. - -OBJ_cmp() compares B to B. If the two are identical 0 is returned. - -OBJ_dup() returns a copy of B. - -OBJ_create() adds a new object to the internal table. B is the -numerical form of the object, B the short name and B 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. - -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: - - ASN1_OBJECT *o; - o = OBJ_nid2obj(NID_commonName); - -Check if an object is B - - 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 to determine the amount of data that should be written. -Instead B must point to a valid buffer and B 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 structure or B is an -error occurred. - -OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B -on error. - -OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return -a NID or B on error. - -=head1 SEE ALSO - -L - -=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 - - 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 manual page. - -=head1 SEE ALSO - -L - -=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 # 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 -- cgit v1.2.3-55-g6feb