2 This is some preliminary documentation for OpenSSL.
4 ==============================================================================
6 ==============================================================================
8 The buffer library handles simple character arrays. Buffers are used for various
9 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 "miscelanous" 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 -config 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 include 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 defines the value of the or how
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 Raw extensions allow arbitrary data to be placed in an extension. For
188 1.2.3.4=critical,RAW:01:02:03:04
191 The value following RAW is a hex dump of the extension contents. Any extension
192 can be placed in this form to override the default behaviour. For example:
194 basicConstraints=critical,RAW:00:01:02:03
196 WARNING: raw extensions should be used with caution. It is possible to create
197 totally invalid extensions unless care is taken.
199 CURRENTLY SUPPORTED EXTENSIONS.
201 Literal String extensions.
203 In each case the 'value' of the extension is placed directly in the extension.
204 Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
205 nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and nsComment.
209 nsComment="This is a test comment"
213 Bit string extensions just consist of a list of suppported bits, currently
214 two extensions are in this category: PKIX keyUsage and the Netscape specific
217 nsCertType (netscape certificate type) takes the flags: client, server, email,
218 objsign, reserved, sslCA, emailCA, objCA.
220 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
221 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
222 encipherOnly, decipherOnly.
228 keyUsage=critical, digitalSignature, nonRepudiation
233 Basic constraints is a multi valued extension that supports a CA and an
234 optional pathlen option. The CA option takes the values true and false and
235 pathlen takes an integer. Note if the CA option is false the pathlen option
240 basicConstraints=CA:TRUE
241 basicConstraints=critical,CA:TRUE, pathlen:10
243 NOTE: for a CA to be considered valid it must have the CA option set to
244 TRUE. An end user certificate MUST NOT have the CA value set to true.
245 According to PKIX recommendations it should exclude the extension entirely,
246 however some software may require CA set to FALSE for end entity certificates.
248 Subject Key Identifier.
250 This is really a string extension and can take two possible values. Either
251 a hex string giving details of the extension value to include or the word
252 'hash' which then automatically follow PKIX guidelines in selecting and
253 appropriate key identifier. The use of the hex string is strongly discouraged.
255 Example: subjectKeyIdentifier=hash
257 Authority Key Identifier.
259 The authority key identifier extension permits two options. keyid and issuer:
260 both can take the optional value "always".
262 If the keyid option is present an attempt is made to copy the subject key
263 identifier from the parent certificate. If the value "always" is present
264 then an error is returned if the option fails.
266 The issuer option copies the issuer and serial number from the issuer
267 certificate. Normally this will only be done if the keyid option fails or
268 is not included: the "always" flag will always include the value.
270 Subject Alternative Name.
272 The subject alternative name extension allows various literal values to be
273 included in the configuration file. These include "email" (an email address)
274 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
275 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
277 Also the email option include a special 'copy' value. This will automatically
278 include and email addresses contained in the certificate subject name in
283 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
284 subjectAltName=email:my@other.address,RID:1.2.3.4
286 Issuer Alternative Name.
288 The issuer alternative name option supports all the literal options of
289 subject alternative name. It does *not* support the email:copy option because
290 that would not make sense. It does support an additional issuer:copy option
291 that will copy all the subject alternative name values from the issuer
292 certificate (if possible).
294 CRL distribution points.
296 This is a multivalued extension that supports all the literal options of
297 subject alternative name. Of the few software packages that currently interpret
298 this extension most only interpret the URI option.
300 Currently each option will set a new DistributionPoint with the fullName
301 field set to the given value.
303 Other fields like cRLissuer and reasons cannot currently be set or displayed:
304 at this time no examples were available that used these fields.
306 If you see this extension with <UNSUPPORTED> when you attempt to print it out
307 or it doesn't appear to display correctly then let me know, including the
308 certificate (mail me at steve@openssl.org) .
312 crlDistributionPoints=URI:http://www.myhost.com/myca.crl
313 crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl
315 Certificate Policies.
317 This is a RAW extension. It attempts to display the contents of this extension:
318 unfortuntately this extension is often improperly encoded.
320 The certificate policies extension will rarely be used in practice: few
321 software packages interpret it correctly or at all. IE5 does partially
322 support this extension: but it needs the 'ia5org' option because it will
323 only correctly support a broken encoding. Of the options below only the
324 policy OID, explicitText and CPS options are displayed with IE5.
326 All the fields of this extension can be set by using the appropriate syntax.
328 If you follow the PKIX recommendations of not including any qualifiers and just
329 using only one OID then you just include the value of that OID. Multiple OIDs
330 can be set separated by commas, for example:
332 certificatePolicies= 1.2.4.5, 1.1.3.4
334 If you wish to include qualifiers then the policy OID and qualifiers need to
335 be specified in a separate section: this is done by using the @section syntax
336 instead of a literal OID value.
338 The section referred to must include the policy OID using the name
339 policyIdentifier, cPSuri qualifiers can be included using the syntax:
343 userNotice qualifiers can be set using the syntax:
345 userNotice.nnn=@notice
347 The value of the userNotice qualifier is specified in the relevant section. This
348 section can include explicitText, organization and noticeNumbers options.
349 explicitText and organization are text strings, noticeNumbers is a comma
350 separated list of numbers. The organization and noticeNumbers options (if
351 included) must BOTH be present. If you use the userNotice option with IE5 then
352 you need the 'ia5org' option at the top level to modify the encoding: otherwise
353 it will not be interpreted properly.
357 certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
361 policyIdentifier = 1.3.5.8
362 CPS.1="http://my.host.name/"
363 CPS.2="http://my.your.name/"
368 explicitText="Explicit Text Here"
369 organization="Organisation Name"
370 noticeNumbers=1,2,3,4
372 TECHNICAL NOTE: the ia5org option changes the type of the 'organization' field,
373 according to PKIX it should be of type DisplayText but Verisign uses an
374 IA5STRING and IE5 needs this too.
376 Display only extensions.
378 Some extensions are only partially supported and currently are only displayed
379 but cannot be set. These include private key usage period, CRL number, and
382 ==============================================================================
384 ==============================================================================
386 This section describes the internal PKCS#12 support. There are very few
387 differences between the old external library and the new internal code at
388 present. This may well change because the external library will not be updated
391 This version now includes a couple of high level PKCS#12 functions which
392 generally "do the right thing" and should make it much easier to handle PKCS#12
395 HIGH LEVEL FUNCTIONS.
397 For most applications you only need concern yourself with the high level
398 functions. They can parse and generate simple PKCS#12 files as produced by
399 Netscape and MSIE or indeed any compliant PKCS#12 file containing a single
400 private key and certificate pair.
402 1. Initialisation and cleanup.
404 No special initialisation is needed for the internal PKCS#12 library: the
405 standard SSLeay_add_all_algorithms() is sufficient. If you do not wish to
406 add all algorithms (you should at least add SHA1 though) then you can manually
407 initialise the PKCS#12 library with:
411 The memory allocated by the PKCS#12 libray is freed up when EVP_cleanup() is
412 called or it can be directly freed with:
416 after this call (or EVP_cleanup() ) no more PKCS#12 library functions should
421 i2d_PKCS12_bio(bp, p12)
423 This writes out a PKCS12 structure to a BIO.
425 i2d_PKCS12_fp(fp, p12)
427 This is the same but for a FILE pointer.
429 d2i_PKCS12_bio(bp, p12)
431 This reads in a PKCS12 structure from a BIO.
433 d2i_PKCS12_fp(fp, p12)
435 This is the same but for a FILE pointer.
437 3. Parsing and creation functions.
439 3.1 Parsing with PKCS12_parse().
441 int PKCS12_parse(PKCS12 *p12, char *pass, EVP_PKEY **pkey, X509 **cert,
444 This function takes a PKCS12 structure and a password (ASCII, null terminated)
445 and returns the private key, the corresponding certificate and any CA
446 certificates. If any of these is not required it can be passed as a NULL.
447 The 'ca' parameter should be either NULL, a pointer to NULL or a valid STACK
448 structure. Typically to read in a PKCS#12 file you might do:
450 p12 = d2i_PKCS12_fp(fp, NULL);
451 PKCS12_parse(p12, password, &pkey, &cert, NULL); /* CAs not wanted */
454 3.2 PKCS#12 creation with PKCS12_create().
456 PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert,
457 STACK *ca, int nid_key, int nid_cert, int iter,
458 int mac_iter, int keytype);
460 This function will create a PKCS12 structure from a given password, name,
461 private key, certificate and optional STACK of CA certificates. The remaining
462 5 parameters can be set to 0 and sensible defaults will be used.
464 The parameters nid_key and nid_cert are the key and certificate encryption
465 algorithms, iter is the encryption iteration count, mac_iter is the MAC
466 iteration count and keytype is the type of private key. If you really want
467 to know what these last 5 parameters do then read the low level section.
469 Typically to create a PKCS#12 file the following could be used:
471 p12 = PKCS12_create(pass, "My Certificate", pkey, cert, NULL, 0,0,0,0,0);
472 i2d_PKCS12_fp(fp, p12);
477 In some cases the high level functions do not provide the necessary
478 functionality. For example if you want to generate or parse more complex PKCS#12
479 files. The sample pkcs12 application uses the low level functions to display
480 details about the internal structure of a PKCS#12 file.
484 This is a brief description of how a PKCS#12 file is represented internally:
485 some knowledge of PKCS#12 is assumed.
487 A PKCS#12 object contains several levels.
489 At the lowest level is a PKCS12_SAFEBAG. This can contain a certificate, a
490 CRL, a private key, encrypted or unencrypted, a set of safebags (so the
491 structure can be nested) or other secrets (not documented at present).
492 A safebag can optionally have attributes, currently these are: a unicode
493 friendlyName (a Unicode string) or a localKeyID (a string of bytes).
495 At the next level is an authSafe which is a set of safebags collected into
496 a PKCS#7 ContentInfo. This can be just plain data, or encrypted itself.
498 At the top level is the PKCS12 structure itself which contains a set of
499 authSafes in an embedded PKCS#7 Contentinfo of type data. In addition it
500 contains a MAC which is a kind of password protected digest to preserve
501 integrity (so any unencrypted stuff below can't be tampered with).
503 The reason for these levels is so various objects can be encrypted in various
504 ways. For example you might want to encrypt a set of private keys with
505 triple-DES and then include the related certificates either unencrypted or with
506 lower encryption. Yes it's the dreaded crypto laws at work again which
507 allow strong encryption on private keys and only weak encryption on other stuff.
509 To build one of these things you turn all certificates and keys into safebags
510 (with optional attributes). You collect the safebags into (one or more) STACKS
511 and convert these into authsafes (encrypted or unencrypted). The authsafes are
512 collected into a STACK and added to a PKCS12 structure. Finally a MAC inserted.
514 Pulling one apart is basically the reverse process. The MAC is verified against
515 the given password. The authsafes are extracted and each authsafe split into
516 a set of safebags (possibly involving decryption). Finally the safebags are
517 decomposed into the original keys and certificates and the attributes used to
518 match up private key and certificate pairs.
520 Anyway here are the functions that do the dirty work.
522 1. Construction functions.
524 1.1 Safebag functions.
526 M_PKCS12_x5092certbag(x509)
528 This macro takes an X509 structure and returns a certificate bag. The
529 X509 structure can be freed up after calling this function.
531 M_PKCS12_x509crl2certbag(crl)
533 As above but for a CRL.
535 PKCS8_PRIV_KEY_INFO *PKEY2PKCS8(EVP_PKEY *pkey)
537 Take a private key and convert it into a PKCS#8 PrivateKeyInfo structure.
538 Works for both RSA and DSA private keys. NB since the PKCS#8 PrivateKeyInfo
539 structure contains a private key data in plain text form it should be free'd up
540 as soon as it has been encrypted for security reasons (freeing up the structure
541 zeros out the sensitive data). This can be done with PKCS8_PRIV_KEY_INFO_free().
543 PKCS8_add_keyusage(PKCS8_PRIV_KEY_INFO *p8, int usage)
545 This sets the key type when a key is imported into MSIE or Outlook 98. Two
546 values are currently supported: KEY_EX and KEY_SIG. KEY_EX is an exchange type
547 key that can also be used for signing but its size is limited in the export
548 versions of MS software to 512 bits, it is also the default. KEY_SIG is a
549 signing only key but the keysize is unlimited (well 16K is supposed to work).
550 If you are using the domestic version of MSIE then you can ignore this because
551 KEY_EX is not limited and can be used for both.
553 PKCS12_SAFEBAG *PKCS12_MAKE_KEYBAG(PKCS8_PRIV_KEY_INFO *p8)
555 Convert a PKCS8 private key structure into a keybag. This routine embeds the p8
556 structure in the keybag so p8 should not be freed up or used after it is called.
557 The p8 structure will be freed up when the safebag is freed.
559 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)
561 Convert a PKCS#8 structure into a shrouded key bag (encrypted). p8 is not
562 embedded and can be freed up after use.
564 int PKCS12_add_localkeyid(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen)
565 int PKCS12_add_friendlyname(PKCS12_SAFEBAG *bag, unsigned char *name, int namelen)
567 Add a local key id or a friendlyname to a safebag.
569 1.2 Authsafe functions.
571 PKCS7 *PKCS12_pack_p7data(STACK *sk)
572 Take a stack of safebags and convert them into an unencrypted authsafe. The
573 stack of safebags can be freed up after calling this function.
575 PKCS7 *PKCS12_pack_p7encdata(int pbe_nid, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, STACK *bags);
577 As above but encrypted.
579 1.3 PKCS12 functions.
581 PKCS12 *PKCS12_init(int mode)
583 Initialise a PKCS12 structure (currently mode should be NID_pkcs7_data).
585 M_PKCS12_pack_authsafes(p12, safes)
587 This macro takes a STACK of authsafes and adds them to a PKCS#12 structure.
589 int PKCS12_set_mac(PKCS12 *p12, unsigned char *pass, int passlen, unsigned char *salt, int saltlen, int iter, EVP_MD *md_type);
591 Add a MAC to a PKCS12 structure. If EVP_MD is NULL use SHA-1, the spec suggests
592 that SHA-1 should be used.
594 2. Extraction Functions.
598 M_PKCS12_bag_type(bag)
600 Return the type of "bag". Returns one of the following
603 NID_pkcs8ShroudedKeyBag 7
607 NID_safeContentsBag 11
609 M_PKCS12_cert_bag_type(bag)
611 Returns type of certificate bag, following are understood.
613 NID_x509Certificate 14
614 NID_sdsiCertificate 15
616 M_PKCS12_crl_bag_type(bag)
618 Returns crl bag type, currently only NID_crlBag is recognised.
620 M_PKCS12_certbag2x509(bag)
622 This macro extracts an X509 certificate from a certificate bag.
624 M_PKCS12_certbag2x509crl(bag)
626 As above but for a CRL.
628 EVP_PKEY * PKCS82PKEY(PKCS8_PRIV_KEY_INFO *p8)
630 Extract a private key from a PKCS8 private key info structure.
632 M_PKCS12_decrypt_skey(bag, pass, passlen)
634 Decrypt a shrouded key bag and return a PKCS8 private key info structure.
635 Works with both RSA and DSA keys
637 char *PKCS12_get_friendlyname(bag)
639 Returns the friendlyName of a bag if present or NULL if none. The returned
640 string is a null terminated ASCII string allocated with Malloc(). It should
641 thus be freed up with Free() after use.
643 2.2 AuthSafe functions.
645 M_PKCS12_unpack_p7data(p7)
647 Extract a STACK of safe bags from a PKCS#7 data ContentInfo.
649 #define M_PKCS12_unpack_p7encdata(p7, pass, passlen)
651 As above but for an encrypted content info.
653 2.3 PKCS12 functions.
655 M_PKCS12_unpack_authsafes(p12)
657 Extract a STACK of authsafes from a PKCS12 structure.
659 M_PKCS12_mac_present(p12)
661 Check to see if a MAC is present.
663 int PKCS12_verify_mac(PKCS12 *p12, unsigned char *pass, int passlen)
665 Verify a MAC on a PKCS12 structure. Returns an error if MAC not present.
670 1. All the function return 0 or NULL on error.
671 2. Encryption based functions take a common set of parameters. These are
675 ASCII password and length. The password on the MAC is called the "integrity
676 password" the encryption password is called the "privacy password" in the
677 PKCS#12 documentation. The passwords do not have to be the same. If -1 is
678 passed for the length it is worked out by the function itself (currently
679 this is sometimes done whatever is passed as the length but that may change).
682 A 'salt' if salt is NULL a random salt is used. If saltlen is also zero a
683 default length is used.
686 Iteration count. This is a measure of how many times an internal function is
687 called to encrypt the data. The larger this value is the longer it takes, it
688 makes dictionary attacks on passwords harder. NOTE: Some implementations do
689 not support an iteration count on the MAC. If the password for the MAC and
690 encryption is the same then there is no point in having a high iteration
691 count for encryption if the MAC has no count. The MAC could be attacked
692 and the password used for the main decryption.
695 This is the NID of the password based encryption method used. The following are
697 NID_pbe_WithSHA1And128BitRC4
698 NID_pbe_WithSHA1And40BitRC4
699 NID_pbe_WithSHA1And3_Key_TripleDES_CBC
700 NID_pbe_WithSHA1And2_Key_TripleDES_CBC
701 NID_pbe_WithSHA1And128BitRC2_CBC
702 NID_pbe_WithSHA1And40BitRC2_CBC
704 Which you use depends on the implementation you are exporting to. "Export grade"(i.e. cryptograhically challenged) products cannot support all algorithms.
705 Typically you may be able to use any encryption on shrouded key bags but they
706 must then be placed in an unencrypted authsafe. Other authsafes may only support
707 40bit encryption. Of course if you are using SSLeay throughout you can strongly
708 encrypt everything and have high iteration counts on everything.
710 3. For decryption routines only the password and length are needed.
712 4. Unlike the external version the nid's of objects are the values of the
713 constants: that is NID_certBag is the real nid, therefore there is no
714 PKCS12_obj_offset() function. Note the object constants are not the same as
715 those of the external version. If you use these constants then you will need
716 to recompile your code.
718 5. With the exception of PKCS12_MAKE_KEYBAG(), after calling any function or
719 macro of the form PKCS12_MAKE_SOMETHING(other) the "other" structure can be
720 reused or freed up safely.