secure/lib/libcrypto/man/X509_NAME_add_entry_by_txt.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH X509_NAME_add_entry_by_txt 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
 192 X509_NAME_add_entry, X509_NAME_delete_entry \- X509_NAME modification functions
 193 .SH "SYNOPSIS"
 194 int \fIX509_NAME_add_entry_by_txt\fR\|(X509_NAME *name, char *field, int type, unsigned char *bytes, int len, int loc, int set);
 195 int \fIX509_NAME_add_entry_by_OBJ\fR\|(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set);
 196 int \fIX509_NAME_add_entry_by_NID\fR\|(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set);
 197 int \fIX509_NAME_add_entry\fR\|(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set);
 198 X509_NAME_ENTRY *\fIX509_NAME_delete_entry\fR\|(X509_NAME *name, int loc);
 199 .SH "DESCRIPTION"
 200 \fIX509_NAME_add_entry_by_txt()\fR, \fIX509_NAME_add_entry_by_OBJ()\fR and
 201 \fIX509_NAME_add_entry_by_NID()\fR add a field whose name is defined
 202 by a string \fBfield\fR, an object \fBobj\fR or a NID \fBnid\fR respectively.
 203 The field value to be added is in \fBbytes\fR of length \fBlen\fR. If
 204 \fBlen\fR is \-1 then the field length is calculated internally using
 205 \fIstrlen\fR\|(bytes).
 206 .PP
 207 The type of field is determined by \fBtype\fR which can either be a
 208 definition of the type of \fBbytes\fR (such as \fBMBSTRING_ASC\fR) or a
 209 standard ASN1 type (such as \fBV_ASN1_IA5STRING\fR). The new entry is
 210 added to a position determined by \fBloc\fR and \fBset\fR.
 211 .PP
 212 \fIX509_NAME_add_entry()\fR adds a copy of \fBX509_NAME_ENTRY\fR structure \fBne\fR
 213 to \fBname\fR. The new entry is added to a position determined by \fBloc\fR
 214 and \fBset\fR. Since a copy of \fBne\fR is added \fBne\fR must be freed up after
 215 the call.
 216 .PP
 217 \fIX509_NAME_delete_entry()\fR deletes an entry from \fBname\fR at position
 218 \fBloc\fR. The deleted entry is returned and must be freed up.
 219 .SH "NOTES"
 220 The use of string types such as \fBMBSTRING_ASC\fR or \fBMBSTRING_UTF8\fR
 221 is strongly recommened for the \fBtype\fR parameter. This allows the
 222 internal code to correctly determine the type of the field and to
 223 apply length checks according to the relevant standards. This is
 224 done using \fIASN1_STRING_set_by_NID()\fR.
 225 .PP
 226 If instead an ASN1 type is used no checks are performed and the
 227 supplied data in \fBbytes\fR is used directly.
 228 .PP
 229 In \fIX509_NAME_add_entry_by_txt()\fR the \fBfield\fR string represents
 230 the field name using \fIOBJ_txt2obj\fR\|(field, 0).
 231 .PP
 232 The \fBloc\fR and \fBset\fR parameters determine where a new entry should
 233 be added. For almost all applications \fBloc\fR can be set to \-1 and \fBset\fR
 234 to 0. This adds a new entry to the end of \fBname\fR as a single valued
 235 RelativeDistinguishedName (RDN).
 236 .PP
 237 \fBloc\fR actually determines the index where the new entry is inserted:
 238 if it is \-1 it is appended.
 239 .PP
 240 \fBset\fR determines how the new type is added. If it is zero a
 241 new RDN is created.
 242 .PP
 243 If \fBset\fR is \-1 or 1 it is added to the previous or next RDN
 244 structure respectively. This will then be a multivalued RDN:
 245 since multivalues RDNs are very seldom used \fBset\fR is almost
 246 always set to zero.
 247 .SH "EXAMPLES"
 248 Create an \fBX509_NAME\fR structure:
 249 .PP
 250 \*(L"C=UK, O=Disorganized Organization, CN=Joe Bloggs\*(R"
 251 .PP
 252 .Vb 13
 253 \& X509_NAME *nm;
 254 \& nm = X509_NAME_new();
 255 \& if (nm == NULL)
 256 \&        /* Some error */
 257 \& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
 258 \&                        "C", "UK", -1, -1, 0))
 259 \&        /* Error */
 260 \& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
 261 \&                        "O", "Disorganized Organization", -1, -1, 0))
 262 \&        /* Error */
 263 \& if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
 264 \&                        "CN", "Joe Bloggs", -1, -1, 0))
 265 \&        /* Error */
 266 .Ve
 267 .SH "RETURN VALUES"
 268 \fIX509_NAME_add_entry_by_txt()\fR, \fIX509_NAME_add_entry_by_OBJ()\fR,
 269 \fIX509_NAME_add_entry_by_NID()\fR and \fIX509_NAME_add_entry()\fR return 1 for
 270 success of 0 if an error occurred.
 271 .PP
 272 \fIX509_NAME_delete_entry()\fR returns either the deleted \fBX509_NAME_ENTRY\fR
 273 structure of \fBNULL\fR if an error occurred.
 274 .SH "BUGS"
 275 \fBtype\fR can still be set to \fBV_ASN1_APP_CHOOSE\fR to use a
 276 different algorithm to determine field types. Since this form does
 277 not understand multicharacter types, performs no length checks and
 278 can result in invalid field types its use is strongly discouraged.
 279 .SH "SEE ALSO"
 280 ERR_get_error(3), d2i_X509_NAME(3)
 281 .SH "HISTORY"
 282
 283 .rn }` ''
 284 .IX Title "X509_NAME_add_entry_by_txt 3"
 285 .IX Name "X509_NAME_add_entry_by_txt, X509_NAME_add_entry_by_OBJ, X509_NAME_add_entry_by_NID,
 286 X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions"
 287
 288 .IX Header "NAME"
 289
 290 .IX Header "SYNOPSIS"
 291
 292 .IX Header "DESCRIPTION"
 293
 294 .IX Header "NOTES"
 295
 296 .IX Header "EXAMPLES"
 297
 298 .IX Header "RETURN VALUES"
 299
 300 .IX Header "BUGS"
 301
 302 .IX Header "SEE ALSO"
 303
 304 .IX Header "HISTORY"
 305