]>
Commit | Line | Data |
---|---|---|
0711be16 DSH |
1 | =pod |
2 | ||
d479dc1d DSH |
3 | =head1 NAME |
4 | ||
0711be16 DSH |
5 | X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID, |
6 | X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions | |
7 | ||
0711be16 DSH |
8 | =head1 SYNOPSIS |
9 | ||
c264592d | 10 | #include <openssl/x509.h> |
c3e64028 | 11 | |
c264592d | 12 | int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set); |
c3e64028 | 13 | |
c264592d | 14 | int X509_NAME_add_entry_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set); |
c3e64028 | 15 | |
c264592d | 16 | int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set); |
c3e64028 | 17 | |
c264592d UM |
18 | int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set); |
19 | ||
20 | X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); | |
0711be16 DSH |
21 | |
22 | =head1 DESCRIPTION | |
23 | ||
24 | X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ() and | |
25 | X509_NAME_add_entry_by_NID() add a field whose name is defined | |
26 | by a string B<field>, an object B<obj> or a NID B<nid> respectively. | |
27 | The field value to be added is in B<bytes> of length B<len>. If | |
28 | B<len> is -1 then the field length is calculated internally using | |
29 | strlen(bytes). | |
30 | ||
31 | The type of field is determined by B<type> which can either be a | |
32 | definition of the type of B<bytes> (such as B<MBSTRING_ASC>) or a | |
33 | standard ASN1 type (such as B<V_ASN1_IA5STRING>). The new entry is | |
34 | added to a position determined by B<loc> and B<set>. | |
35 | ||
36 | X509_NAME_add_entry() adds a copy of B<X509_NAME_ENTRY> structure B<ne> | |
37 | to B<name>. The new entry is added to a position determined by B<loc> | |
38 | and B<set>. Since a copy of B<ne> is added B<ne> must be freed up after | |
39 | the call. | |
40 | ||
41 | X509_NAME_delete_entry() deletes an entry from B<name> at position | |
42 | B<loc>. The deleted entry is returned and must be freed up. | |
43 | ||
44 | =head1 NOTES | |
45 | ||
46 | The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8> | |
cda01d55 | 47 | is strongly recommended for the B<type> parameter. This allows the |
0711be16 DSH |
48 | internal code to correctly determine the type of the field and to |
49 | apply length checks according to the relevant standards. This is | |
50 | done using ASN1_STRING_set_by_NID(). | |
51 | ||
52 | If instead an ASN1 type is used no checks are performed and the | |
53 | supplied data in B<bytes> is used directly. | |
54 | ||
55 | In X509_NAME_add_entry_by_txt() the B<field> string represents | |
56 | the field name using OBJ_txt2obj(field, 0). | |
57 | ||
58 | The B<loc> and B<set> parameters determine where a new entry should | |
59 | be added. For almost all applications B<loc> can be set to -1 and B<set> | |
60 | to 0. This adds a new entry to the end of B<name> as a single valued | |
61 | RelativeDistinguishedName (RDN). | |
62 | ||
63 | B<loc> actually determines the index where the new entry is inserted: | |
64 | if it is -1 it is appended. | |
65 | ||
66 | B<set> determines how the new type is added. If it is zero a | |
67 | new RDN is created. | |
68 | ||
69 | If B<set> is -1 or 1 it is added to the previous or next RDN | |
70 | structure respectively. This will then be a multivalued RDN: | |
71 | since multivalues RDNs are very seldom used B<set> is almost | |
72 | always set to zero. | |
73 | ||
74 | =head1 EXAMPLES | |
75 | ||
76 | Create an B<X509_NAME> structure: | |
77 | ||
78 | "C=UK, O=Disorganized Organization, CN=Joe Bloggs" | |
79 | ||
80 | X509_NAME *nm; | |
81 | nm = X509_NAME_new(); | |
82 | if (nm == NULL) | |
83 | /* Some error */ | |
f281b8df MC |
84 | if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC, |
85 | "UK", -1, -1, 0)) | |
0711be16 | 86 | /* Error */ |
f281b8df MC |
87 | if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC, |
88 | "Disorganized Organization", -1, -1, 0)) | |
0711be16 | 89 | /* Error */ |
f281b8df MC |
90 | if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC, |
91 | "Joe Bloggs", -1, -1, 0)) | |
0711be16 DSH |
92 | /* Error */ |
93 | ||
94 | =head1 RETURN VALUES | |
95 | ||
96 | X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(), | |
97 | X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for | |
98 | success of 0 if an error occurred. | |
99 | ||
100 | X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY> | |
101 | structure of B<NULL> if an error occurred. | |
102 | ||
103 | =head1 BUGS | |
104 | ||
105 | B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a | |
106 | different algorithm to determine field types. Since this form does | |
107 | not understand multicharacter types, performs no length checks and | |
108 | can result in invalid field types its use is strongly discouraged. | |
109 | ||
110 | =head1 SEE ALSO | |
111 | ||
9b86974e | 112 | L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> |
0711be16 DSH |
113 | |
114 | =head1 HISTORY | |
115 | ||
116 | =cut | |
e2f92610 RS |
117 | |
118 | =head1 COPYRIGHT | |
119 | ||
120 | Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. | |
121 | ||
122 | Licensed under the OpenSSL license (the "License"). You may not use | |
123 | this file except in compliance with the License. You can obtain a copy | |
124 | in the file LICENSE in the source distribution or at | |
125 | L<https://www.openssl.org/source/license.html>. | |
126 | ||
127 | =cut |