1 files changed, 165 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/ASN1_STRING_length.3 b/src/lib/libcrypto/man/ASN1_STRING_length.3
new file mode 100644
index 0000000000..71744587be
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_STRING_length.3
@@ -0,0 +1,165 @@
+.Dd July 17, 2014
+.Dt ASN1_STRING_LENGTH 3
+.Os
+.Sh NAME
+.Nm ASN1_STRING_cmp ,
+.Nm ASN1_STRING_data ,
+.Nm ASN1_STRING_dup ,
+.Nm ASN1_STRING_length ,
+.Nm ASN1_STRING_length_set ,
+.Nm ASN1_STRING_set ,
+.Nm ASN1_STRING_to_UTF8 ,
+.Nm ASN1_STRING_type
+.Nd ASN1_STRING utility functions
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo ASN1_STRING_cmp
+.Fa "ASN1_STRING *a"
+.Fa "ASN1_STRING *b"
+.Fc
+.Ft unsigned char *
+.Fo ASN1_STRING_data
+.Fa "ASN1_STRING *x"
+.Fc
+.Ft ASN1_STRING *
+.Fo ASN1_STRING_dup
+.Fa "ASN1_STRING *a"
+.Fc
+.Ft int
+.Fo ASN1_STRING_length
+.Fa "ASN1_STRING *x"
+.Fc
+.Ft void
+.Fo ASN1_STRING_length_set
+.Fa "ASN1_STRING *x"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo ASN1_STRING_set
+.Fa "ASN1_STRING *str"
+.Fa "const void *data"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo ASN1_STRING_to_UTF8
+.Fa "unsigned char **out"
+.Fa "ASN1_STRING *in"
+.Fc
+.Ft int
+.Fo ASN1_STRING_type
+.Fa "ASN1_STRING *x"
+.Fc
+.Sh DESCRIPTION
+These functions manipulate
+.Vt ASN1_STRING
+structures.
+.Pp
+.Fn ASN1_STRING_cmp
+compares
+.Fa a
+and
+.Fa b
+and returns 0 if the two are identical.
+The string types and the content are compared.
+.Pp
+.Fn ASN1_STRING_data
+returns an internal pointer to the data of
+.Fa x .
+Since this is an internal pointer, it should
+.Em not
+be freed or modified in any way.
+.Pp
+.Fn ASN1_STRING_dup
+returns a copy of the structure
+.Fa a .
+.Pp
+.Fn ASN1_STRING_length
+returns the length of the content of
+.Fa x .
+.Pp
+.Fn ASN1_STRING_length_set
+sets the length attribute of
+.Fa x
+to
+.Fa len .
+It may put
+.Fa x
+into an inconsistent internal state.
+.Pp
+.Fn ASN1_STRING_set
+sets the data of the string
+.Fa str
+to the buffer
+.Fa data
+of length
+.Fa len .
+The supplied data is copied.
+If
+.Fa len
+is -1 then the length is determined by
+.Fn strlen data .
+.Pp
+.Fn ASN1_STRING_to_UTF8
+converts the string
+.Fa in
+to UTF8 format.
+The converted data is copied into a newly allocated buffer
+.Fa out .
+The length of
+.Fa out
+is returned or a negative error code.
+The buffer
+.Fa out
+should be freed using
+.Xr free 3 .
+.Pp
+.Fn ASN1_STRING_type
+returns the type of
+.Fa x ,
+using standard constants such as
+.Dv V_ASN1_OCTET_STRING .
+.Sh NOTES
+Almost all ASN1 types in OpenSSL are represented as
+.Vt ASN1_STRING
+structures.
+Other types such as
+.Vt ASN1_OCTET_STRING
+are simply typedefed to
+.Vt ASN1_STRING
+and the functions call the
+.Vt ASN1_STRING
+equivalents.
+.Vt ASN1_STRING
+is also used for some
+.Sy CHOICE
+types which consist entirely of primitive string types such as
+.Sy DirectoryString
+and
+.Sy Time .
+.Pp
+These functions should
+.Em not
+be used to examine or modify
+.Vt ASN1_INTEGER
+or
+.Vt ASN1_ENUMERATED
+types: the relevant
+.Sy INTEGER
+or
+.Sy ENUMERATED
+utility functions should be used instead.
+.Pp
+In general it cannot be assumed that the data returned by
+.Fn ASN1_STRING_data
+is NUL terminated, and it may contain embedded NUL characters.
+The actual format of the data will depend on the actual string type itself:
+for example for an IA5String the data will be ASCII,
+for a BMPString two bytes per character in big endian format,
+UTF8String will be in UTF8 format.
+.Pp
+Similar care should be take to ensure the data is in the correct format
+when calling
+.Fn ASN1_STRING_set .
+.Sh SEE ALSO
+.Xr ERR_get_error 3

diff --git a/src/lib/libcrypto/man/ASN1_STRING_length.3 b/src/lib/libcrypto/man/ASN1_STRING_length.3 new file mode 100644 index 0000000000..71744587be --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_STRING_length.3
@@ -0,0 +1,165 @@
	1	.Dd July 17, 2014
	2	.Dt ASN1_STRING_LENGTH 3
	3	.Os
	4	.Sh NAME
	5	.Nm ASN1_STRING_cmp ,
	6	.Nm ASN1_STRING_data ,
	7	.Nm ASN1_STRING_dup ,
	8	.Nm ASN1_STRING_length ,
	9	.Nm ASN1_STRING_length_set ,
	10	.Nm ASN1_STRING_set ,
	11	.Nm ASN1_STRING_to_UTF8 ,
	12	.Nm ASN1_STRING_type
	13	.Nd ASN1_STRING utility functions
	14	.Sh SYNOPSIS
	15	.In openssl/asn1.h
	16	.Ft int
	17	.Fo ASN1_STRING_cmp
	18	.Fa "ASN1_STRING *a"
	19	.Fa "ASN1_STRING *b"
	20	.Fc
	21	.Ft unsigned char *
	22	.Fo ASN1_STRING_data
	23	.Fa "ASN1_STRING *x"
	24	.Fc
	25	.Ft ASN1_STRING *
	26	.Fo ASN1_STRING_dup
	27	.Fa "ASN1_STRING *a"
	28	.Fc
	29	.Ft int
	30	.Fo ASN1_STRING_length
	31	.Fa "ASN1_STRING *x"
	32	.Fc
	33	.Ft void
	34	.Fo ASN1_STRING_length_set
	35	.Fa "ASN1_STRING *x"
	36	.Fa "int len"
	37	.Fc
	38	.Ft int
	39	.Fo ASN1_STRING_set
	40	.Fa "ASN1_STRING *str"
	41	.Fa "const void *data"
	42	.Fa "int len"
	43	.Fc
	44	.Ft int
	45	.Fo ASN1_STRING_to_UTF8
	46	.Fa "unsigned char **out"
	47	.Fa "ASN1_STRING *in"
	48	.Fc
	49	.Ft int
	50	.Fo ASN1_STRING_type
	51	.Fa "ASN1_STRING *x"
	52	.Fc
	53	.Sh DESCRIPTION
	54	These functions manipulate
	55	.Vt ASN1_STRING
	56	structures.
	57	.Pp
	58	.Fn ASN1_STRING_cmp
	59	compares
	60	.Fa a
	61	and
	62	.Fa b
	63	and returns 0 if the two are identical.
	64	The string types and the content are compared.
	65	.Pp
	66	.Fn ASN1_STRING_data
	67	returns an internal pointer to the data of
	68	.Fa x .
	69	Since this is an internal pointer, it should
	70	.Em not
	71	be freed or modified in any way.
	72	.Pp
	73	.Fn ASN1_STRING_dup
	74	returns a copy of the structure
	75	.Fa a .
	76	.Pp
	77	.Fn ASN1_STRING_length
	78	returns the length of the content of
	79	.Fa x .
	80	.Pp
	81	.Fn ASN1_STRING_length_set
	82	sets the length attribute of
	83	.Fa x
	84	to
	85	.Fa len .
	86	It may put
	87	.Fa x
	88	into an inconsistent internal state.
	89	.Pp
	90	.Fn ASN1_STRING_set
	91	sets the data of the string
	92	.Fa str
	93	to the buffer
	94	.Fa data
	95	of length
	96	.Fa len .
	97	The supplied data is copied.
	98	If
	99	.Fa len
	100	is -1 then the length is determined by
	101	.Fn strlen data .
	102	.Pp
	103	.Fn ASN1_STRING_to_UTF8
	104	converts the string
	105	.Fa in
	106	to UTF8 format.
	107	The converted data is copied into a newly allocated buffer
	108	.Fa out .
	109	The length of
	110	.Fa out
	111	is returned or a negative error code.
	112	The buffer
	113	.Fa out
	114	should be freed using
	115	.Xr free 3 .
	116	.Pp
	117	.Fn ASN1_STRING_type
	118	returns the type of
	119	.Fa x ,
	120	using standard constants such as
	121	.Dv V_ASN1_OCTET_STRING .
	122	.Sh NOTES
	123	Almost all ASN1 types in OpenSSL are represented as
	124	.Vt ASN1_STRING
	125	structures.
	126	Other types such as
	127	.Vt ASN1_OCTET_STRING
	128	are simply typedefed to
	129	.Vt ASN1_STRING
	130	and the functions call the
	131	.Vt ASN1_STRING
	132	equivalents.
	133	.Vt ASN1_STRING
	134	is also used for some
	135	.Sy CHOICE
	136	types which consist entirely of primitive string types such as
	137	.Sy DirectoryString
	138	and
	139	.Sy Time .
	140	.Pp
	141	These functions should
	142	.Em not
	143	be used to examine or modify
	144	.Vt ASN1_INTEGER
	145	or
	146	.Vt ASN1_ENUMERATED
	147	types: the relevant
	148	.Sy INTEGER
	149	or
	150	.Sy ENUMERATED
	151	utility functions should be used instead.
	152	.Pp
	153	In general it cannot be assumed that the data returned by
	154	.Fn ASN1_STRING_data
	155	is NUL terminated, and it may contain embedded NUL characters.
	156	The actual format of the data will depend on the actual string type itself:
	157	for example for an IA5String the data will be ASCII,
	158	for a BMPString two bytes per character in big endian format,
	159	UTF8String will be in UTF8 format.
	160	.Pp
	161	Similar care should be take to ensure the data is in the correct format
	162	when calling
	163	.Fn ASN1_STRING_set .
	164	.Sh SEE ALSO
	165	.Xr ERR_get_error 3