RSA Key Formats

This document explains the various ways in which RSA keys can be stored, and how the CryptoSys PKI Toolkit handles them.

Creating a new key pair

The function RSA_MakeKeys creates a new RSA key pair in two files, one for the public key and one for the private key. The private key is saved in encrypted form, protected by a password supplied by the user, so it is never saved explicitly to disk in the clear.

Creating a X.509 certificate

To create an X.509 certificate, you use the function X509_MakeCert like this:

Creating an X.509 certificate

There is special kind of certificate called a "self-signed" certificate, normally made by a Certification Authority (CA), but you can make your own using the key pair you created above and the X509_MakeCertSelf function:

Creating a self-signed X.509 certificate

You can use this certificate together with the private key to sign certificates for other subjects. You can also import this certificate into your own PC using the CERTMGR.EXE program as a "Trusted Root Certification Authority". Your system will then "trust" all certificates issued by the self-signed certificate. (CAUTION: never install an unknown certificate on your computer as trusted; you never know what mischief it may allow).

In practice, you use your own private key and the X509_CertRequest function to create a Certificate Signing Request and then send it along with a fee to someone like Verisign who will issue a properly-trusted certificate and return it to you.

Creating a certificate signing request

Internal Representation

Most functions involving RSA keys in the CryptoSys PKI Toolkit require the public or private key to be provided as a string in an "internal" format. A few functions require the actual key file itself. This internal format is actually a base64-encoded form of the key but please treat it as an opaque "blob" because we may change the format in later versions. There are a variety of functions provided to extract the public and private keys from files of various formats and to save them back to alternative formats.

These functions are explained diagrammatically in this diagram of RSA Key Functions in CryptoSys PKI (updated April 2006 for new functions in version 2.8).

Key File Encoding

Key data may be encoded in three general ways:

Binary BER-encoded format. This is sometimes called ASN.1 DER-encoded (there is a subtle difference between BER- and DER-encodings). The most compact form. If you try to view the file with a text editor it is full of "funny" characters. The first character in the file is almost always a '0' character (0x30).
PEM or base64 format. This is the same data as the BER-encoded file but it is encoded in base64 with additional header and footer lines:
```
-----BEGIN FOO BAR KEY-----
MIIBgjAcBgoqhkiG9w0BDAEDMA4ECKZesfWLQOiDAgID6ASCAWBu7izm8N4V
2puRO/Mdt+Y8ceywxiC0cE57nrbmvaTSvBwTg9b/xyd8YC6QK7lrhC9Njgp/
...
-----END FOO BAR KEY-----
```
These files can be viewed with a text editor and can be easily transmitted as part of an email message.
XML format. There are W3C standards for this, and, er, a .NET way that predates the latest W3C standard.

How to read in an RSA Key

X.509 public key certificates are usually named .cer or .der. A PEM-format version might be named .pem. An X.509 certificate is essentially a signed copy of the user's public key plus various other identifying information. There is no accepted convention, though, for naming the raw public and private key files: .pub, .pri, .key, .bin and .pem are frequently used (we use .epk in some of our examples for encrypted private keys - but this is solely our own naming convention).

You can recover the public key directly from a single X.509 certificate using the RSA_GetPublicKeyFromCert function, or you can read it in from a BER or PEM public key file using RSA_ReadPublicKey. In both cases you end up with the public key in "internal" string format.

You read in a private key from a BER or PEM file using either the RSA_ReadEncPrivateKey function plus a password, or using the RSA_ReadPrivateKeyInfo function if the file is not encrypted.

To read in from an XML file, in all cases, XML data needs to be read into a string and then reconstructed using the RSA_FromXMLString function. See Importing an RSA key from known parameters.

Public key certificates can also come in Cryptographic Message Syntax Standard PKCS#7 format (typically named .p7b or .p7c, but sometimes mischeviously named .cer) or as part of a PKCS#12 PFX file (typically called .pfx or .p12). The PKCS#7 files might contain several certificates in a chain. Use the X509_GetCertFromP7Chain and X509_GetCertFromPFX functions to extract a single X.509 certificate from P7c and PFX files respectively. Encrypted private keys can also come in PFX format: use the RSA_GetPrivateKeyFromPFX function to extract a PKCS#8 encrypted private key file.

Public and private key formats supported

These "raw" public and private key formats are supported by the CryptoSys PKI Toolkit:

Public key formats supported

PKCS#1 RSAPublicKey* (PEM header: BEGIN RSA PUBLIC KEY)
X.509 SubjectPublicKeyInfo** (PEM header: BEGIN PUBLIC KEY)
XML <RSAKeyValue>

Encrypted private key format supported

PKCS#8 EncryptedPrivateKeyInfo** (PEM header: BEGIN ENCRYPTED PRIVATE KEY)

Private key formats supported (unencrypted)

PKCS#1 RSAPrivateKey** (PEM header: BEGIN RSA PRIVATE KEY)
PKCS#8 PrivateKeyInfo* (PEM header: BEGIN PRIVATE KEY)
XML <RSAKeyPair> and <RSAKeyValue>

* compatible with the examples in S/MIME Examples [SMIME-EX]
** compatible with OpenSLL

References

[NIST80057] NIST Special Publication 800-57, Recommendation for Key Management - Part 1: General, National Institute of Standards and Technology, DRAFT, April, 2005.
[PKCS1] PKCS #1, RSA Cryptography Standard, RSA Laboratories, Version 2.1, June 2002.
[PKCS8] PKCS #8, Private-Key Information Syntax Standard, RSA Laboratories, Version 1.2, Nov 1993.
[PKCS12] PKCS #12, Private-Key Information Syntax Standard, RSA Laboratories, Version 1.2, Nov 1993.
[RFC3850] RFC 3850, Network Working Group Request for Comments: 3850, Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.1 Certificate Handling, B. Ramsdell, July 2004.
[SMIME-EX] RFC 4134, Network Working Group Request for Comments: 4134, Examples of S/MIME Messages, P. Hoffman, July 2005.
[XKMS] W3C Recommendation, XML Key Management Specification (XKMS 2.0), <http://www.w3.org/TR/xkms2/>, 28 June 2005.
[XMLSIG] W3C Recommendation, XML-Signature Syntax and Processing, <http://www.w3.org/TR/xmldsig-core/>, 12 February 2002.

This page last updated: 13 May 2006

Home | PKI Home | Purchase | Cryptography Software Code | Contact us
Copyright © 2005-6 D.I. Management Services Pty Limited ABN 78 083 210 584, Sydney, Australia. All rights reserved.
<www.di-mgt.com.au> <www.cryptosys.net>