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