Document X509_ALGOR_new(3) and X509_ALGOR_free(3)

listed in <openssl/x509.h> and in OpenSSL doc/man3/X509_dup.pod. Explain what an X509_ALGOR object represents and where it is used. Explain how copying works, like in similar pages. New RETURN VALUES, SEE ALSO, and STANDARDS sections. Some macro and wording fixes.
author: schwarze <> 2016-12-15 22:08:23 +0000
committer: schwarze <> 2016-12-15 22:08:23 +0000
commit: b17865ed36ce1e1c66954c264d9dab466b31cae9 (patch)
tree: 46b5d235788bc8846859ec0e0096a7dc88931339 /src/lib
parent: b986d0958179c04d1b3e40e1ee4310fda3e96fec (diff)
download: openbsd-b17865ed36ce1e1c66954c264d9dab466b31cae9.tar.gz
openbsd-b17865ed36ce1e1c66954c264d9dab466b31cae9.tar.bz2
openbsd-b17865ed36ce1e1c66954c264d9dab466b31cae9.zip
1 files changed, 81 insertions, 17 deletions
diff --git a/src/lib/libcrypto/man/X509_ALGOR_dup.3 b/src/lib/libcrypto/man/X509_ALGOR_dup.3
index 5ca80dc3f8..370dbc71db 100644
--- a/src/lib/libcrypto/man/X509_ALGOR_dup.3
+++ b/src/lib/libcrypto/man/X509_ALGOR_dup.3
@@ -1,7 +1,24 @@
-.\"     $OpenBSD: X509_ALGOR_dup.3,v 1.2 2016/12/05 16:38:24 jmc Exp $
+.\"     $OpenBSD: X509_ALGOR_dup.3,v 1.3 2016/12/15 22:08:23 schwarze Exp $
 .\"     OpenSSL 4692340e Jun 7 15:49:08 2016 -0400
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2002, 2015 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,19 +65,25 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 5 2016 $
+.Dd $Mdocdate: December 15 2016 $
 .Dt X509_ALGOR_DUP 3
 .Os
 .Sh NAME
+.Nm X509_ALGOR_new ,
+.Nm X509_ALGOR_free ,
 .Nm X509_ALGOR_dup ,
 .Nm X509_ALGOR_set0 ,
 .Nm X509_ALGOR_get0 ,
 .Nm X509_ALGOR_set_md ,
 .Nm X509_ALGOR_cmp
-.Nd AlgorithmIdentifier functions
+.Nd create, change, and inspect algorithm identifiers
 .Sh SYNOPSIS
 .In openssl/x509.h
 .Ft X509_ALGOR *
+.Fn X509_ALGOR_new void
+.Ft void
+.Fn X509_ALGOR_free "X509_ALGOR *alg"
+.Ft X509_ALGOR *
 .Fo X509_ALGOR_dup
 .Fa "X509_ALGOR *alg"
 .Fc
@@ -89,9 +112,27 @@
 .Fa "const X509_ALGOR *b"
 .Fc
 .Sh DESCRIPTION
+.Fn X509_ALGOR_new
+allocates and initializes an empty
+.Vt X509_ALGOR
+object, representing an ASN.1 AlgorithmIdentifier structure
+defined in RFC 5280 section 4.1.1.2.
+Such objects can specify a cryptographic algorithm together
+with algorithm-specific parameters.
+They are used by many other objects, for example certificates,
+certificate revocation lists, and certificate requests.
+.Pp
+.Fn X509_ALGOR_free
+frees
+.Fa alg.
+.Pp
 .Fn X509_ALGOR_dup
-returns a copy of
+copies
-.Fa alg .
+.Fa alg
+by calling
+.Xr i2d_X509_ALGOR 3
+and
+.Xr d2i_X509_ALGOR 3 .
 .Pp
 .Fn X509_ALGOR_set0
 sets the algorithm OID of
@@ -105,15 +146,15 @@ with value
 If
 .Fa ptype
 is
-.Sy V_ASN1_UNDEF
+.Dv V_ASN1_UNDEF
 the parameter is omitted, otherwise
 .Fa ptype
 and
 .Fa pval
 have the same meaning as the
-.Sy type
+.Fa type
 and
-.Sy value
+.Fa value
 parameters to
 .Xr ASN1_TYPE_set 3 .
 All the supplied parameters are used internally so must
@@ -124,18 +165,16 @@ be freed after this call.
 is the inverse of
 .Fn X509_ALGOR_set0 :
 it returns the algorithm OID in
-.Sy *paobj
+.Pf * Fa paobj
 and the associated parameter in
-.Sy *pptype
+.Pf * Fa pptype
 and
-.Sy *ppval
+.Pf * Fa ppval
-from the
+from
-.Sy AlgorithmIdentifier
 .Fa alg .
 .Pp
 .Fn X509_ALGOR_set_md
-sets the
+sets
-.Sy AlgorithmIdentifier
 .Fa alg
 to appropriate values for the message digest
 .Fa md .
@@ -144,5 +183,30 @@ to appropriate values for the message digest
 compares
 .Fa a
 and
+.Fa b .
+.Sh RETURN VALUES
+.Fn X509_ALGOR_new
+and
+.Fn X509_ALGOR_dup
+return a new
+.Vt X509_ALGOR
+object or
+.Dv NULL
+if an error occurs.
+.Pp
+.Fn X509_ALGOR_set0
+returns 1 for success or 0 for failure.
+.Pp
+.Fn X509_ALGOR_cmp
+returns 0 if
+.Fa a
+and
 .Fa b
-and returns 0 if they have identical encodings and non-zero otherwise.
+have identical encodings or non-zero otherwise.
+.Sh SEE ALSO
+.Xr ASN1_TYPE_set 3 ,
+.Xr d2i_X509_ALGOR 3 ,
+.Xr X509_PUBKEY_get0_param 3
+.Sh STANDARDS
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
+Certificate Revocation List (CRL) Profile
author	schwarze <>	2016-12-15 22:08:23 +0000
committer	schwarze <>	2016-12-15 22:08:23 +0000
commit	b17865ed36ce1e1c66954c264d9dab466b31cae9 (patch)
tree	46b5d235788bc8846859ec0e0096a7dc88931339 /src/lib
parent	b986d0958179c04d1b3e40e1ee4310fda3e96fec (diff)
download	openbsd-b17865ed36ce1e1c66954c264d9dab466b31cae9.tar.gz openbsd-b17865ed36ce1e1c66954c264d9dab466b31cae9.tar.bz2 openbsd-b17865ed36ce1e1c66954c264d9dab466b31cae9.zip

diff --git a/src/lib/libcrypto/man/X509_ALGOR_dup.3 b/src/lib/libcrypto/man/X509_ALGOR_dup.3 index 5ca80dc3f8..370dbc71db 100644 --- a/src/lib/libcrypto/man/X509_ALGOR_dup.3 +++ b/src/lib/libcrypto/man/X509_ALGOR_dup.3
@@ -1,7 +1,24 @@
1	.\" $OpenBSD: X509_ALGOR_dup.3,v 1.2 2016/12/05 16:38:24 jmc Exp $	1	.\" $OpenBSD: X509_ALGOR_dup.3,v 1.3 2016/12/15 22:08:23 schwarze Exp $
2	.\" OpenSSL 4692340e Jun 7 15:49:08 2016 -0400	2	.\" OpenSSL 4692340e Jun 7 15:49:08 2016 -0400
3	.\"	3	.\"
4	.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.	4	.\" This file is a derived work.
		5	.\" The changes are covered by the following Copyright and license:
		6	.\"
		7	.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
		8	.\"
		9	.\" Permission to use, copy, modify, and distribute this software for any
		10	.\" purpose with or without fee is hereby granted, provided that the above
		11	.\" copyright notice and this permission notice appear in all copies.
		12	.\"
		13	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
		14	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
		15	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
		16	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
		17	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
		18	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
		19	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
		20	.\"
		21	.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
5	.\" Copyright (c) 2002, 2015 The OpenSSL Project. All rights reserved.	22	.\" Copyright (c) 2002, 2015 The OpenSSL Project. All rights reserved.
6	.\"	23	.\"
7	.\" Redistribution and use in source and binary forms, with or without	24	.\" Redistribution and use in source and binary forms, with or without
@@ -48,19 +65,25 @@
48	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED	65	.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49	.\" OF THE POSSIBILITY OF SUCH DAMAGE.	66	.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50	.\"	67	.\"
51	.Dd $Mdocdate: December 5 2016 $	68	.Dd $Mdocdate: December 15 2016 $
52	.Dt X509_ALGOR_DUP 3	69	.Dt X509_ALGOR_DUP 3
53	.Os	70	.Os
54	.Sh NAME	71	.Sh NAME
		72	.Nm X509_ALGOR_new ,
		73	.Nm X509_ALGOR_free ,
55	.Nm X509_ALGOR_dup ,	74	.Nm X509_ALGOR_dup ,
56	.Nm X509_ALGOR_set0 ,	75	.Nm X509_ALGOR_set0 ,
57	.Nm X509_ALGOR_get0 ,	76	.Nm X509_ALGOR_get0 ,
58	.Nm X509_ALGOR_set_md ,	77	.Nm X509_ALGOR_set_md ,
59	.Nm X509_ALGOR_cmp	78	.Nm X509_ALGOR_cmp
60	.Nd AlgorithmIdentifier functions	79	.Nd create, change, and inspect algorithm identifiers
61	.Sh SYNOPSIS	80	.Sh SYNOPSIS
62	.In openssl/x509.h	81	.In openssl/x509.h
63	.Ft X509_ALGOR *	82	.Ft X509_ALGOR *
		83	.Fn X509_ALGOR_new void
		84	.Ft void
		85	.Fn X509_ALGOR_free "X509_ALGOR *alg"
		86	.Ft X509_ALGOR *
64	.Fo X509_ALGOR_dup	87	.Fo X509_ALGOR_dup
65	.Fa "X509_ALGOR *alg"	88	.Fa "X509_ALGOR *alg"
66	.Fc	89	.Fc
@@ -89,9 +112,27 @@
89	.Fa "const X509_ALGOR *b"	112	.Fa "const X509_ALGOR *b"
90	.Fc	113	.Fc
91	.Sh DESCRIPTION	114	.Sh DESCRIPTION
		115	.Fn X509_ALGOR_new
		116	allocates and initializes an empty
		117	.Vt X509_ALGOR
		118	object, representing an ASN.1 AlgorithmIdentifier structure
		119	defined in RFC 5280 section 4.1.1.2.
		120	Such objects can specify a cryptographic algorithm together
		121	with algorithm-specific parameters.
		122	They are used by many other objects, for example certificates,
		123	certificate revocation lists, and certificate requests.
		124	.Pp
		125	.Fn X509_ALGOR_free
		126	frees
		127	.Fa alg.
		128	.Pp
92	.Fn X509_ALGOR_dup	129	.Fn X509_ALGOR_dup
93	returns a copy of	130	copies
94	.Fa alg .	131	.Fa alg
		132	by calling
		133	.Xr i2d_X509_ALGOR 3
		134	and
		135	.Xr d2i_X509_ALGOR 3 .
95	.Pp	136	.Pp
96	.Fn X509_ALGOR_set0	137	.Fn X509_ALGOR_set0
97	sets the algorithm OID of	138	sets the algorithm OID of
@@ -105,15 +146,15 @@ with value
105	If	146	If
106	.Fa ptype	147	.Fa ptype
107	is	148	is
108	.Sy V_ASN1_UNDEF	149	.Dv V_ASN1_UNDEF
109	the parameter is omitted, otherwise	150	the parameter is omitted, otherwise
110	.Fa ptype	151	.Fa ptype
111	and	152	and
112	.Fa pval	153	.Fa pval
113	have the same meaning as the	154	have the same meaning as the
114	.Sy type	155	.Fa type
115	and	156	and
116	.Sy value	157	.Fa value
117	parameters to	158	parameters to
118	.Xr ASN1_TYPE_set 3 .	159	.Xr ASN1_TYPE_set 3 .
119	All the supplied parameters are used internally so must	160	All the supplied parameters are used internally so must
@@ -124,18 +165,16 @@ be freed after this call.
124	is the inverse of	165	is the inverse of
125	.Fn X509_ALGOR_set0 :	166	.Fn X509_ALGOR_set0 :
126	it returns the algorithm OID in	167	it returns the algorithm OID in
127	.Sy *paobj	168	.Pf * Fa paobj
128	and the associated parameter in	169	and the associated parameter in
129	.Sy *pptype	170	.Pf * Fa pptype
130	and	171	and
131	.Sy *ppval	172	.Pf * Fa ppval
132	from the	173	from
133	.Sy AlgorithmIdentifier
134	.Fa alg .	174	.Fa alg .
135	.Pp	175	.Pp
136	.Fn X509_ALGOR_set_md	176	.Fn X509_ALGOR_set_md
137	sets the	177	sets
138	.Sy AlgorithmIdentifier
139	.Fa alg	178	.Fa alg
140	to appropriate values for the message digest	179	to appropriate values for the message digest
141	.Fa md .	180	.Fa md .
@@ -144,5 +183,30 @@ to appropriate values for the message digest
144	compares	183	compares
145	.Fa a	184	.Fa a
146	and	185	and
		186	.Fa b .
		187	.Sh RETURN VALUES
		188	.Fn X509_ALGOR_new
		189	and
		190	.Fn X509_ALGOR_dup
		191	return a new
		192	.Vt X509_ALGOR
		193	object or
		194	.Dv NULL
		195	if an error occurs.
		196	.Pp
		197	.Fn X509_ALGOR_set0
		198	returns 1 for success or 0 for failure.
		199	.Pp
		200	.Fn X509_ALGOR_cmp
		201	returns 0 if
		202	.Fa a
		203	and
147	.Fa b	204	.Fa b
148	and returns 0 if they have identical encodings and non-zero otherwise.	205	have identical encodings or non-zero otherwise.
		206	.Sh SEE ALSO
		207	.Xr ASN1_TYPE_set 3 ,
		208	.Xr d2i_X509_ALGOR 3 ,
		209	.Xr X509_PUBKEY_get0_param 3
		210	.Sh STANDARDS
		211	RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
		212	Certificate Revocation List (CRL) Profile