2 This is some preliminary documentation for OpenSSL.
4 ==============================================================================
6 ==============================================================================
8 The buffer library handles simple character arrays. Buffers are used for
9 various purposes in the library, most notably memory BIOs.
11 The library uses the BUF_MEM structure defined in buffer.h:
13 typedef struct buf_mem_st
15 int length; /* current number of bytes */
17 int max; /* size of buffer */
20 'length' is the current size of the buffer in bytes, 'max' is the amount of
21 memory allocated to the buffer. There are three functions which handle these
22 and one "miscellaneous" function.
24 BUF_MEM *BUF_MEM_new()
26 This allocates a new buffer of zero size. Returns the buffer or NULL on error.
28 void BUF_MEM_free(BUF_MEM *a)
30 This frees up an already existing buffer. The data is zeroed before freeing
31 up in case the buffer contains sensitive data.
33 int BUF_MEM_grow(BUF_MEM *str, int len)
35 This changes the size of an already existing buffer. It returns zero on error
36 or the new size (i.e. 'len'). Any data already in the buffer is preserved if
39 char * BUF_strdup(char *str)
41 This is the previously mentioned strdup function: like the standard library
42 strdup() it copies a null terminated string into a block of allocated memory
43 and returns a pointer to the allocated block.
45 Unlike the standard C library strdup() this function uses Malloc() and so
46 should be used in preference to the standard library strdup() because it can
47 be used for memory leak checking or replacing the malloc() function.
49 The memory allocated from BUF_strdup() should be freed up using the Free()
52 ==============================================================================
53 OpenSSL X509V3 extension configuration
54 ==============================================================================
56 OpenSSL X509V3 extension configuration: preliminary documentation.
60 For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
61 possible to add and print out common X509 V3 certificate and CRL extensions.
63 For more information about the meaning of extensions see:
65 http://www.imc.org/ietf-pkix/
66 http://home.netscape.com/eng/security/certs.html
70 Extension values are automatically printed out for supported extensions.
72 openssl x509 -in cert.pem -text
73 openssl crl -in crl.pem -text
75 will give information in the extension printout, for example:
79 X509v3 Basic Constraints:
81 X509v3 Subject Key Identifier:
82 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
83 X509v3 Authority Key Identifier:
84 keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00
86 Certificate Sign, CRL Sign
87 X509v3 Subject Alternative Name:
88 email:email@1.address, email:email@2.address
92 The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
93 which certificate extensions to include. In each case a line:
95 x509_extensions = extension_section
97 indicates which section contains the extensions. In the case of 'req' the
98 extension section is used when the -x509 option is present to create a
99 self signed root certificate.
101 The 'x509' utility also supports extensions when it signs a certificate.
102 The -extfile option is used to set the configuration file containing the
103 extensions. In this case a line with:
105 extensions = extension_section
107 in the nameless (default) section is used. If no such line is included then
108 it uses the default section.
110 You can also add extensions to CRLs: a line
112 crl_extensions = crl_extension_section
114 will include extensions when the -gencrl option is used with the 'ca' utility.
115 You can add any extension to a CRL but of the supported extensions only
116 issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
117 CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
118 CRL entry extensions can be displayed.
120 NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL
121 you should comment out the crl_extensions line in the configuration file.
123 As with all configuration files you can use the inbuilt environment expansion
124 to allow the values to be passed in the environment. Therefore if you have
125 several extension sections used for different purposes you can have a line:
127 x509_extensions = $ENV::ENV_EXT
129 and set the ENV_EXT environment variable before calling the relevant utility.
133 Extensions have the basic form:
135 extension_name=[critical,] extension_options
137 the use of the critical option makes the extension critical. Extreme caution
138 should be made when using the critical flag. If an extension is marked
139 as critical then any client that does not understand the extension should
140 reject it as invalid. Some broken software will reject certificates which
141 have *any* critical extensions (these violates PKIX but we have to live
144 There are three main types of extension: string extensions, multi-valued
145 extensions, and raw extensions.
147 String extensions simply have a string which contains either the value itself
148 or how it is obtained.
152 nsComment="This is a Comment"
154 Multi-valued extensions have a short form and a long form. The short form
155 is a list of names and values:
157 basicConstraints=critical,CA:true,pathlen:1
159 The long form allows the values to be placed in a separate section:
161 basicConstraints=critical,@bs_section
168 Both forms are equivalent. However it should be noted that in some cases the
169 same name can appear multiple times, for example,
171 subjectAltName=email:steve@here,email:steve@there
173 in this case an equivalent long form is:
175 subjectAltName=@alt_section
182 This is because the configuration file code cannot handle the same name
183 occurring twice in the same extension.
185 The syntax of raw extensions is governed by the extension code: it can
186 for example contain data in multiple sections. The correct syntax to
187 use is defined by the extension code itself: check out the certificate
188 policies extension for an example.
190 In addition it is also possible to use the word DER to include arbitrary
191 data in any extension.
193 1.2.3.4=critical,DER:01:02:03:04
196 The value following DER is a hex dump of the DER encoding of the extension
197 Any extension can be placed in this form to override the default behaviour.
200 basicConstraints=critical,DER:00:01:02:03
202 WARNING: DER should be used with caution. It is possible to create totally
203 invalid extensions unless care is taken.
205 CURRENTLY SUPPORTED EXTENSIONS.
207 Literal String extensions.
209 In each case the 'value' of the extension is placed directly in the
210 extension. Currently supported extensions in this category are: nsBaseUrl,
211 nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl,
212 nsSslServerName and nsComment.
216 nsComment="This is a test comment"
220 Bit string extensions just consist of a list of supported bits, currently
221 two extensions are in this category: PKIX keyUsage and the Netscape specific
224 nsCertType (netscape certificate type) takes the flags: client, server, email,
225 objsign, reserved, sslCA, emailCA, objCA.
227 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
228 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
229 encipherOnly, decipherOnly.
235 keyUsage=critical, digitalSignature, nonRepudiation
240 Basic constraints is a multi-valued extension that supports a CA and an
241 optional pathlen option. The CA option takes the values true and false and
242 pathlen takes an integer. Note if the CA option is false the pathlen option
247 basicConstraints=CA:TRUE
248 basicConstraints=critical,CA:TRUE, pathlen:10
250 NOTE: for a CA to be considered valid it must have the CA option set to
251 TRUE. An end user certificate MUST NOT have the CA value set to true.
252 According to PKIX recommendations it should exclude the extension entirely,
253 however some software may require CA set to FALSE for end entity certificates.
255 Subject Key Identifier.
257 This is really a string extension and can take two possible values. Either
258 a hex string giving details of the extension value to include or the word
259 'hash' which then automatically follow PKIX guidelines in selecting and
260 appropriate key identifier. The use of the hex string is strongly discouraged.
262 Example: subjectKeyIdentifier=hash
264 Authority Key Identifier.
266 The authority key identifier extension permits two options. keyid and issuer:
267 both can take the optional value "always".
269 If the keyid option is present an attempt is made to copy the subject key
270 identifier from the parent certificate. If the value "always" is present
271 then an error is returned if the option fails.
273 The issuer option copies the issuer and serial number from the issuer
274 certificate. Normally this will only be done if the keyid option fails or
275 is not included: the "always" flag will always include the value.
277 Subject Alternative Name.
279 The subject alternative name extension allows various literal values to be
280 included in the configuration file. These include "email" (an email address)
281 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
282 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
284 Also the email option include a special 'copy' value. This will automatically
285 include and email addresses contained in the certificate subject name in
290 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
291 subjectAltName=email:my@other.address,RID:1.2.3.4
293 Issuer Alternative Name.
295 The issuer alternative name option supports all the literal options of
296 subject alternative name. It does *not* support the email:copy option because
297 that would not make sense. It does support an additional issuer:copy option
298 that will copy all the subject alternative name values from the issuer
299 certificate (if possible).
301 CRL distribution points.
303 This is a multi-valued extension that supports all the literal options of
304 subject alternative name. Of the few software packages that currently interpret
305 this extension most only interpret the URI option.
307 Currently each option will set a new DistributionPoint with the fullName
308 field set to the given value.
310 Other fields like cRLissuer and reasons cannot currently be set or displayed:
311 at this time no examples were available that used these fields.
313 If you see this extension with <UNSUPPORTED> when you attempt to print it out
314 or it doesn't appear to display correctly then let me know, including the
315 certificate (mail me at steve@openssl.org) .
319 crlDistributionPoints=URI:http://www.myhost.com/myca.crl
320 crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl
322 Certificate Policies.
324 This is a RAW extension. It attempts to display the contents of this extension:
325 unfortunately this extension is often improperly encoded.
327 The certificate policies extension will rarely be used in practice: few
328 software packages interpret it correctly or at all. IE5 does partially
329 support this extension: but it needs the 'ia5org' option because it will
330 only correctly support a broken encoding. Of the options below only the
331 policy OID, explicitText and CPS options are displayed with IE5.
333 All the fields of this extension can be set by using the appropriate syntax.
335 If you follow the PKIX recommendations of not including any qualifiers and just
336 using only one OID then you just include the value of that OID. Multiple OIDs
337 can be set separated by commas, for example:
339 certificatePolicies= 1.2.4.5, 1.1.3.4
341 If you wish to include qualifiers then the policy OID and qualifiers need to
342 be specified in a separate section: this is done by using the @section syntax
343 instead of a literal OID value.
345 The section referred to must include the policy OID using the name
346 policyIdentifier, cPSuri qualifiers can be included using the syntax:
350 userNotice qualifiers can be set using the syntax:
352 userNotice.nnn=@notice
354 The value of the userNotice qualifier is specified in the relevant section.
355 This section can include explicitText, organization and noticeNumbers
356 options. explicitText and organization are text strings, noticeNumbers is a
357 comma separated list of numbers. The organization and noticeNumbers options
358 (if included) must BOTH be present. If you use the userNotice option with IE5
359 then you need the 'ia5org' option at the top level to modify the encoding:
360 otherwise it will not be interpreted properly.
364 certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
368 policyIdentifier = 1.3.5.8
369 CPS.1="http://my.host.name/"
370 CPS.2="http://my.your.name/"
375 explicitText="Explicit Text Here"
376 organization="Organisation Name"
377 noticeNumbers=1,2,3,4
379 TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field,
380 according to PKIX it should be of type DisplayText but Verisign uses an
381 IA5STRING and IE5 needs this too.
383 Display only extensions.
385 Some extensions are only partially supported and currently are only displayed
386 but cannot be set. These include private key usage period, CRL number, and
389 ==============================================================================
391 ==============================================================================
393 This section describes the internal PKCS#12 support. There are very few
394 differences between the old external library and the new internal code at
395 present. This may well change because the external library will not be updated
398 This version now includes a couple of high level PKCS#12 functions which
399 generally "do the right thing" and should make it much easier to handle PKCS#12
402 HIGH LEVEL FUNCTIONS.
404 For most applications you only need concern yourself with the high level
405 functions. They can parse and generate simple PKCS#12 files as produced by
406 Netscape and MSIE or indeed any compliant PKCS#12 file containing a single
407 private key and certificate pair.
409 1. Initialisation and cleanup.
411 No special initialisation is needed for the internal PKCS#12 library: the
412 standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to
413 add all algorithms (you should at least add SHA1 though) then you can manually
414 initialise the PKCS#12 library with:
418 The memory allocated by the PKCS#12 library is freed up when EVP_cleanup() is
419 called or it can be directly freed with:
423 after this call (or EVP_cleanup() ) no more PKCS#12 library functions should
428 i2d_PKCS12_bio(bp, p12)
430 This writes out a PKCS12 structure to a BIO.
432 i2d_PKCS12_fp(fp, p12)
434 This is the same but for a FILE pointer.
436 d2i_PKCS12_bio(bp, p12)
438 This reads in a PKCS12 structure from a BIO.
440 d2i_PKCS12_fp(fp, p12)
442 This is the same but for a FILE pointer.
444 3. Parsing and creation functions.
446 3.1 Parsing with PKCS12_parse().
448 int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert,
451 This function takes a PKCS12 structure and a password (ASCII, null terminated)
452 and returns the private key, the corresponding certificate and any CA
453 certificates. If any of these is not required it can be passed as a NULL.
454 The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK
455 structure. Typically to read in a PKCS#12 file you might do:
457 p12 = d2i_PKCS12_fp(fp, NULL);
458 PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */
461 3.2 PKCS#12 creation with PKCS12_create().
463 PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert,
464 STACK *ca, int nid_key, int nid_cert, int iter,
465 int mac_iter, int keytype);
467 This function will create a PKCS12 structure from a given password, name,
468 private key, certificate and optional STACK of CA certificates. The remaining
469 5 parameters can be set to 0 and sensible defaults will be used.
471 The parameters nid_key and nid_cert are the key and certificate encryption
472 algorithms, iter is the encryption iteration count, mac_iter is the MAC
473 iteration count and keytype is the type of private key. If you really want
474 to know what these last 5 parameters do then read the low level section.
476 Typically to create a PKCS#12 file the following could be used:
478 p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0);
479 i2d_PKCS12_fp(fp, p12);
484 In some cases the high level functions do not provide the necessary
485 functionality. For example if you want to generate or parse more complex
486 PKCS#12 files. The sample pkcs12 application uses the low level functions
487 to display details about the internal structure of a PKCS#12 file.
491 This is a brief description of how a PKCS#12 file is represented internally:
492 some knowledge of PKCS#12 is assumed.
494 A PKCS#12 object contains several levels.
496 At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a
497 CRL, a private key, encrypted or unencrypted, a set of safebags (so the
498 structure can be nested) or other secrets (not documented at present).
499 A safebag can optionally have attributes, currently these are: a unicode
500 friendlyName (a Unicode string) or a localKeyID (a string of bytes).
502 At the next level is an authSafe which is a set of safebags collected into
503 a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself.
505 At the top level is the PKCS12 structure itself which contains a set of
506 authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it
507 contains a MAC which is a kind of password protected digest to preserve
508 integrity (so any unencrypted stuff below can't be tampered with).
510 The reason for these levels is so various objects can be encrypted in various
511 ways. For example you might want to encrypt a set of private keys with
512 triple-DES and then include the related certificates either unencrypted or
513 with lower encryption. Yes it's the dreaded crypto laws at work again which
514 allow strong encryption on private keys and only weak encryption on other
517 To build one of these things you turn all certificates and keys into safebags
518 (with optional attributes). You collect the safebags into (one or more) STACKS
519 and convert these into authsafes (encrypted or unencrypted). The authsafes
520 are collected into a STACK and added to a PKCS12 structure. Finally a MAC
523 Pulling one apart is basically the reverse process. The MAC is verified against
524 the given password. The authsafes are extracted and each authsafe split into
525 a set of safebags (possibly involving decryption). Finally the safebags are
526 decomposed into the original keys and certificates and the attributes used to
527 match up private key and certificate pairs.
529 Anyway here are the functions that do the dirty work.
531 1. Construction functions.
533 1.1 Safebag functions.
535 M_PKCS12_x5092certbag(x509)
537 This macro takes an X509 structure and returns a certificate bag. The
538 X509 structure can be freed up after calling this function.
540 M_PKCS12_x509crl2certbag(crl)
542 As above but for a CRL.
544 PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey)
546 Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure.
547 Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo
548 structure contains a private key data in plain text form it should be free'd
549 up as soon as it has been encrypted for security reasons (freeing up the
550 structure zeros out the sensitive data). This can be done with
551 PKCS8_PRIV_KEY_INFO_free().
553 PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage)
555 This sets the key type when a key is imported into MSIE or Outlook 98. Two
556 values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type
557 key that can also be used for signing but its size is limited in the export
558 versions of MS software to 512 bits, it is also the default. KEY_SIG is a
559 signing only key but the keysize is unlimited (well 16K is supposed to work).
560 If you are using the domestic version of MSIE then you can ignore this because
561 KEY_EX is not limited and can be used for both.
563 PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8)
565 Convert a PKCS8 private key structure into a keybag. This routine embeds the
566 p8 structure in the keybag so p8 should not be freed up or used after it is
567 called. The p8 structure will be freed up when the safebag is freed.
569 PKCS12_SAFEBAG *PKCS12_MAKE_SHKEYBAG(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, PKCS8_PRIV_KEY_INFO *p8)
571 Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not
572 embedded and can be freed up after use.
574 int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen)
575 int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen)
577 Add a local key id or a friendlyname to a safebag.
579 1.2 Authsafe functions.
581 PKCS7 *PKCS12_pack_p7data(STACK *sk)
582 Take a stack of safebags and convert them into an unencrypted authsafe. The
583 stack of safebags can be freed up after calling this function.
585 PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags);
587 As above but encrypted.
589 1.3 PKCS12 functions.
591 PKCS12 *PKCS12_init(int mode)
593 Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data).
595 M_PKCS12_pack_authsafes(p12, safes)
597 This macro takes a STACK of authsafes and adds them to a PKCS#12 structure.
599 int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type);
601 Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests
602 that SHA-1 should be used.
604 2. Extraction Functions.
608 M_PKCS12_bag_type(bag)
610 Return the type of "bag". Returns one of the following
613 NID_pkcs8ShroudedKeyBag 7
617 NID_safeContentsBag 11
619 M_PKCS12_cert_bag_type(bag)
621 Returns type of certificate bag, following are understood.
623 NID_x509Certificate 14
624 NID_sdsiCertificate 15
626 M_PKCS12_crl_bag_type(bag)
628 Returns crl bag type, currently only NID_crlBag is recognised.
630 M_PKCS12_certbag2x509(bag)
632 This macro extracts an X509 certificate from a certificate bag.
634 M_PKCS12_certbag2x509crl(bag)
636 As above but for a CRL.
638 EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8)
640 Extract a private key from a PKCS8 private key info structure.
642 M_PKCS12_decrypt_skey(bag, pass, passlen)
644 Decrypt a shrouded key bag and return a PKCS8 private key info structure.
645 Works with both RSA and DSA keys
647 char *PKCS12_get_friendlyname(bag)
649 Returns the friendlyName of a bag if present or NULL if none. The returned
650 string is a null terminated ASCII string allocated with Malloc(). It should
651 thus be freed up with Free() after use.
653 2.2 AuthSafe functions.
655 M_PKCS12_unpack_p7data(p7)
657 Extract a STACK of safe bags from a PKCS#7 data ContentInfo.
659 #define M_PKCS12_unpack_p7encdata(p7, pass, passlen)
661 As above but for an encrypted content info.
663 2.3 PKCS12 functions.
665 M_PKCS12_unpack_authsafes(p12)
667 Extract a STACK of authsafes from a PKCS12 structure.
669 M_PKCS12_mac_present(p12)
671 Check to see if a MAC is present.
673 int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen)
675 Verify a MAC on a PKCS12 structure. Returns an error if MAC not present.
680 1. All the function return 0 or NULL on error.
681 2. Encryption based functions take a common set of parameters. These are
685 ASCII password and length. The password on the MAC is called the "integrity
686 password" the encryption password is called the "privacy password" in the
687 PKCS#12 documentation. The passwords do not have to be the same. If -1 is
688 passed for the length it is worked out by the function itself (currently
689 this is sometimes done whatever is passed as the length but that may change).
692 A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a
693 default length is used.
696 Iteration count. This is a measure of how many times an internal function is
697 called to encrypt the data. The larger this value is the longer it takes, it
698 makes dictionary attacks on passwords harder. NOTE: Some implementations do
699 not support an iteration count on the MAC. If the password for the MAC and
700 encryption is the same then there is no point in having a high iteration
701 count for encryption if the MAC has no count. The MAC could be attacked
702 and the password used for the main decryption.
705 This is the NID of the password based encryption method used. The following are
707 NID_pbe_WithSHA1And128BitRC4
708 NID_pbe_WithSHA1And40BitRC4
709 NID_pbe_WithSHA1And3_Key_TripleDES_CBC
710 NID_pbe_WithSHA1And2_Key_TripleDES_CBC
711 NID_pbe_WithSHA1And128BitRC2_CBC
712 NID_pbe_WithSHA1And40BitRC2_CBC
714 Which you use depends on the implementation you are exporting to. "Export
715 grade" (i.e. cryptographically challenged) products cannot support all
716 algorithms. Typically you may be able to use any encryption on shrouded key
717 bags but they must then be placed in an unencrypted authsafe. Other authsafes
718 may only support 40bit encryption. Of course if you are using SSLeay
719 throughout you can strongly encrypt everything and have high iteration counts
722 3. For decryption routines only the password and length are needed.
724 4. Unlike the external version the nid's of objects are the values of the
725 constants: that is NID_certBag is the real nid, therefore there is no
726 PKCS12_obj_offset() function. Note the object constants are not the same as
727 those of the external version. If you use these constants then you will need
728 to recompile your code.
730 5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or
731 macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be
732 reused or freed up safely.