x509.h File Reference

Copyright (C) 2006-2010, Brainspark B.V.

This file is part of PolarSSL (http://www.polarssl.org) Lead Maintainer: Paul Bakker <polarssl_maintainer at polarssl.org>

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

#include "polarssl/rsa.h"

Data Structures
struct	_x509_buf
struct	_x509_cert
struct	_x509_crl
struct	_x509_crl_entry
struct	_x509_name
struct	_x509_node
struct	_x509_raw
struct	_x509_time

Macros
#define	ASN1_BIT_STRING   0x03
#define	ASN1_BMP_STRING   0x1E
#define	ASN1_BOOLEAN   0x01
#define	ASN1_CONSTRUCTED   0x20
#define	ASN1_CONTEXT_SPECIFIC   0x80
#define	ASN1_GENERALIZED_TIME   0x18
#define	ASN1_IA5_STRING   0x16
#define	ASN1_INTEGER   0x02
#define	ASN1_NULL   0x05
#define	ASN1_OCTET_STRING   0x04
#define	ASN1_OID   0x06
#define	ASN1_PRIMITIVE   0x00
#define	ASN1_PRINTABLE_STRING   0x13
#define	ASN1_SEQUENCE   0x10
#define	ASN1_SET   0x11
#define	ASN1_T61_STRING   0x14
#define	ASN1_UNIVERSAL_STRING   0x1C
#define	ASN1_UTC_TIME   0x17
#define	ASN1_UTF8_STRING   0x0C
#define	BADCERT_CN_MISMATCH   4
#define	BADCERT_EXPIRED   1
#define	BADCERT_NOT_TRUSTED   8
#define	BADCERT_REVOKED   2
#define	BADCRL_EXPIRED   32
#define	BADCRL_NOT_TRUSTED   16
#define	OID_CN   "\x55\x04\x03"
#define	OID_PKCS1   "\x2A\x86\x48\x86\xF7\x0D\x01\x01"
#define	OID_PKCS1_RSA   "\x2A\x86\x48\x86\xF7\x0D\x01\x01\x01"
#define	OID_PKCS1_RSA_SHA   "\x2A\x86\x48\x86\xF7\x0D\x01\x01\x05"
#define	OID_PKCS9   "\x2A\x86\x48\x86\xF7\x0D\x01\x09"
#define	OID_PKCS9_EMAIL   "\x2A\x86\x48\x86\xF7\x0D\x01\x09\x01"
#define	OID_X520   "\x55\x04"
#define	PEM_LINE_LENGTH   72
#define	PKCS9_EMAIL   1
#define	POLARSSL_ERR_ASN1_INVALID_DATA   0x001C
#define	POLARSSL_ERR_ASN1_INVALID_LENGTH   0x0018
#define	POLARSSL_ERR_ASN1_LENGTH_MISMATCH   0x001A
#define	POLARSSL_ERR_ASN1_OUT_OF_DATA   0x0014
#define	POLARSSL_ERR_ASN1_UNEXPECTED_TAG   0x0016
#define	POLARSSL_ERR_X509_CERT_INVALID_ALG   -0x00C0
#define	POLARSSL_ERR_X509_CERT_INVALID_DATE   -0x0100
#define	POLARSSL_ERR_X509_CERT_INVALID_EXTENSIONS   -0x0160
#define	POLARSSL_ERR_X509_CERT_INVALID_FORMAT   -0x0060
#define	POLARSSL_ERR_X509_CERT_INVALID_NAME   -0x00E0
#define	POLARSSL_ERR_X509_CERT_INVALID_PEM   -0x0040
#define	POLARSSL_ERR_X509_CERT_INVALID_PUBKEY   -0x0120
#define	POLARSSL_ERR_X509_CERT_INVALID_SERIAL   -0x00A0
#define	POLARSSL_ERR_X509_CERT_INVALID_SIGNATURE   -0x0140
#define	POLARSSL_ERR_X509_CERT_INVALID_VERSION   -0x0080
#define	POLARSSL_ERR_X509_CERT_SIG_MISMATCH   -0x01E0
#define	POLARSSL_ERR_X509_CERT_UNKNOWN_PK_ALG   -0x01C0
#define	POLARSSL_ERR_X509_CERT_UNKNOWN_SIG_ALG   -0x01A0
#define	POLARSSL_ERR_X509_CERT_UNKNOWN_VERSION   -0x0180
#define	POLARSSL_ERR_X509_CERT_VERIFY_FAILED   -0x0200
#define	POLARSSL_ERR_X509_FEATURE_UNAVAILABLE   -0x0020
#define	POLARSSL_ERR_X509_KEY_INVALID_ENC_IV   -0x0280
#define	POLARSSL_ERR_X509_KEY_INVALID_FORMAT   -0x0260
#define	POLARSSL_ERR_X509_KEY_INVALID_PEM   -0x0220
#define	POLARSSL_ERR_X509_KEY_INVALID_VERSION   -0x0240
#define	POLARSSL_ERR_X509_KEY_PASSWORD_MISMATCH   -0x02E0
#define	POLARSSL_ERR_X509_KEY_PASSWORD_REQUIRED   -0x02C0
#define	POLARSSL_ERR_X509_KEY_UNKNOWN_ENC_ALG   -0x02A0
#define	POLARSSL_ERR_X509_POINT_ERROR   -0x0300
#define	POLARSSL_ERR_X509_VALUE_TO_LENGTH   -0x0320
#define	X509_ISSUER   0x01
#define	X509_OUTPUT_DER   0x01
#define	X509_OUTPUT_PEM   0x02
#define	X509_SUBJECT   0x02
#define	X520_COMMON_NAME   3
#define	X520_COUNTRY   6
#define	X520_LOCALITY   7
#define	X520_ORG_UNIT   11
#define	X520_ORGANIZATION   10
#define	X520_STATE   8

Typedefs
typedef struct _x509_buf	x509_buf
typedef struct _x509_cert	x509_cert
typedef struct _x509_crl	x509_crl
typedef struct _x509_crl_entry	x509_crl_entry
typedef struct _x509_name	x509_name
typedef struct _x509_node	x509_node
typedef struct _x509_raw	x509_raw
typedef struct _x509_time	x509_time

Functions
void	x509_crl_free (x509_crl *crl)
	Unallocate all CRL data. More...
void	x509_free (x509_cert *crt)
	Unallocate all certificate data. More...
int	x509_self_test (int verbose)
	Checkup routine. More...
int	x509parse_cert_info (char *buf, size_t size, const char *prefix, const x509_cert *crt)
	Returns an informational string about the certificate. More...
int	x509parse_crl (x509_crl *chain, const unsigned char *buf, int buflen)
	Parse one or more CRLs and add them to the chained list. More...
int	x509parse_crl_info (char *buf, size_t size, const char *prefix, const x509_crl *crl)
	Returns an informational string about the CRL. More...
int	x509parse_crlfile (x509_crl *chain, const char *path)
	Load one or more CRLs and add them to the chained list. More...
int	x509parse_crt (x509_cert *chain, const unsigned char *buf, int buflen)
	Parse one or more certificates and add them to the chained list. More...
int	x509parse_crtfile (x509_cert *chain, const char *path)
	Load one or more certificates and add them to the chained list. More...
int	x509parse_dn_gets (char *buf, size_t size, const x509_name *dn)
	Store the certificate DN in printable form into buf; no more than size characters will be written. More...
int	x509parse_key (rsa_context *rsa, const unsigned char *key, int keylen, const unsigned char *pwd, int pwdlen)
	Parse a private RSA key. More...
int	x509parse_keyfile (rsa_context *rsa, const char *path, const char *password)
	Load and parse a private RSA key. More...
int	x509parse_time_expired (const x509_time *time)
	Check a given x509_time against the system time and check if it is valid. More...
int	x509parse_verify (x509_cert *crt, x509_cert *trust_ca, x509_crl *ca_crl, const char *cn, int *flags)
	Verify the certificate signature. More...

#define ASN1_BIT_STRING   0x03

#define ASN1_BMP_STRING   0x1E

#define ASN1_BOOLEAN   0x01

#define ASN1_CONSTRUCTED   0x20

#define ASN1_CONTEXT_SPECIFIC   0x80

#define ASN1_GENERALIZED_TIME   0x18

#define ASN1_IA5_STRING   0x16

#define ASN1_INTEGER   0x02

#define ASN1_NULL   0x05

#define ASN1_OCTET_STRING   0x04

#define ASN1_OID   0x06

#define ASN1_PRIMITIVE   0x00

#define ASN1_PRINTABLE_STRING   0x13

#define ASN1_SEQUENCE   0x10

#define ASN1_SET   0x11

#define ASN1_T61_STRING   0x14

#define ASN1_UNIVERSAL_STRING   0x1C

#define ASN1_UTC_TIME   0x17

#define ASN1_UTF8_STRING   0x0C

#define BADCERT_CN_MISMATCH   4

#define BADCERT_EXPIRED   1

#define BADCERT_NOT_TRUSTED   8

#define BADCERT_REVOKED   2

#define BADCRL_EXPIRED   32

#define BADCRL_NOT_TRUSTED   16

#define OID_CN   "\x55\x04\x03"

#define OID_PKCS1   "\x2A\x86\x48\x86\xF7\x0D\x01\x01"

#define OID_PKCS1_RSA   "\x2A\x86\x48\x86\xF7\x0D\x01\x01\x01"

#define OID_PKCS1_RSA_SHA   "\x2A\x86\x48\x86\xF7\x0D\x01\x01\x05"

#define OID_PKCS9   "\x2A\x86\x48\x86\xF7\x0D\x01\x09"

#define OID_PKCS9_EMAIL   "\x2A\x86\x48\x86\xF7\x0D\x01\x09\x01"

#define OID_X520   "\x55\x04"

#define PEM_LINE_LENGTH   72

#define PKCS9_EMAIL   1

#define POLARSSL_ERR_ASN1_INVALID_DATA   0x001C

#define POLARSSL_ERR_ASN1_INVALID_LENGTH   0x0018

#define POLARSSL_ERR_ASN1_LENGTH_MISMATCH   0x001A

#define POLARSSL_ERR_ASN1_OUT_OF_DATA   0x0014

#define POLARSSL_ERR_ASN1_UNEXPECTED_TAG   0x0016

#define POLARSSL_ERR_X509_CERT_INVALID_ALG   -0x00C0

#define POLARSSL_ERR_X509_CERT_INVALID_DATE   -0x0100

#define POLARSSL_ERR_X509_CERT_INVALID_EXTENSIONS   -0x0160

#define POLARSSL_ERR_X509_CERT_INVALID_FORMAT   -0x0060

#define POLARSSL_ERR_X509_CERT_INVALID_NAME   -0x00E0

#define POLARSSL_ERR_X509_CERT_INVALID_PEM   -0x0040

#define POLARSSL_ERR_X509_CERT_INVALID_PUBKEY   -0x0120

#define POLARSSL_ERR_X509_CERT_INVALID_SERIAL   -0x00A0

#define POLARSSL_ERR_X509_CERT_INVALID_SIGNATURE   -0x0140

#define POLARSSL_ERR_X509_CERT_INVALID_VERSION   -0x0080

#define POLARSSL_ERR_X509_CERT_SIG_MISMATCH   -0x01E0

#define POLARSSL_ERR_X509_CERT_UNKNOWN_PK_ALG   -0x01C0

#define POLARSSL_ERR_X509_CERT_UNKNOWN_SIG_ALG   -0x01A0

#define POLARSSL_ERR_X509_CERT_UNKNOWN_VERSION   -0x0180

#define POLARSSL_ERR_X509_CERT_VERIFY_FAILED   -0x0200

#define POLARSSL_ERR_X509_FEATURE_UNAVAILABLE   -0x0020

#define POLARSSL_ERR_X509_KEY_INVALID_ENC_IV   -0x0280

#define POLARSSL_ERR_X509_KEY_INVALID_FORMAT   -0x0260

#define POLARSSL_ERR_X509_KEY_INVALID_PEM   -0x0220

#define POLARSSL_ERR_X509_KEY_INVALID_VERSION   -0x0240

#define POLARSSL_ERR_X509_KEY_PASSWORD_MISMATCH   -0x02E0

#define POLARSSL_ERR_X509_KEY_PASSWORD_REQUIRED   -0x02C0

#define POLARSSL_ERR_X509_KEY_UNKNOWN_ENC_ALG   -0x02A0

#define POLARSSL_ERR_X509_POINT_ERROR   -0x0300

#define POLARSSL_ERR_X509_VALUE_TO_LENGTH   -0x0320

#define X509_ISSUER   0x01

#define X509_OUTPUT_DER   0x01

#define X509_OUTPUT_PEM   0x02

#define X509_SUBJECT   0x02

#define X520_COMMON_NAME   3

#define X520_COUNTRY   6

#define X520_LOCALITY   7

#define X520_ORG_UNIT   11

#define X520_ORGANIZATION   10

#define X520_STATE   8

typedef struct _x509_buf x509_buf

typedef struct _x509_cert x509_cert

typedef struct _x509_crl x509_crl

typedef struct _x509_crl_entry x509_crl_entry

typedef struct _x509_name x509_name

typedef struct _x509_node x509_node

typedef struct _x509_raw x509_raw

typedef struct _x509_time x509_time

void x509_crl_free

(

x509_crl *

crl

)

Unallocate all CRL data.

Parameters

crt	CRL chain to free

void x509_free

(

x509_cert *

crt

)

Unallocate all certificate data.

Parameters

crt	Certificate chain to free

int x509_self_test

(

int

verbose

)

Checkup routine.

Returns

0 if successful, or 1 if the test failed

Referenced by main().

int x509parse_cert_info	(	char *	buf,
		size_t	size,
		const char *	prefix,
		const x509_cert *	crt
	)

Returns an informational string about the certificate.

Parameters

buf	Buffer to write to
size	Maximum size of buffer
prefix	A line prefix
crt	The X509 certificate to represent

Returns

The amount of data written to the buffer, or -1 in case of an error.

int x509parse_crl	(	x509_crl *	chain,
		const unsigned char *	buf,
		int	buflen
	)

Parse one or more CRLs and add them to the chained list.

Parameters

chain	points to the start of the chain
buf	buffer holding the CRL data
buflen	size of the buffer

Returns

0 if successful, or a specific X509 error code

int x509parse_crl_info	(	char *	buf,
		size_t	size,
		const char *	prefix,
		const x509_crl *	crl
	)

Returns an informational string about the CRL.

Parameters

buf	Buffer to write to
size	Maximum size of buffer
prefix	A line prefix
crt	The X509 CRL to represent

Returns

The amount of data written to the buffer, or -1 in case of an error.

int x509parse_crlfile	(	x509_crl *	chain,
		const char *	path
	)

Load one or more CRLs and add them to the chained list.

Parameters

chain	points to the start of the chain
path	filename to read the CRLs from

Returns

0 if successful, or a specific X509 error code

int x509parse_crt	(	x509_cert *	chain,
		const unsigned char *	buf,
		int	buflen
	)

Parse one or more certificates and add them to the chained list.

Parameters

chain	points to the start of the chain
buf	buffer holding the certificate data
buflen	size of the buffer

Returns

0 if successful, or a specific X509 error code

int x509parse_crtfile	(	x509_cert *	chain,
		const char *	path
	)

Load one or more certificates and add them to the chained list.

Parameters

chain	points to the start of the chain
path	filename to read the certificates from

Returns

0 if successful, or a specific X509 error code

int x509parse_dn_gets	(	char *	buf,
		size_t	size,
		const x509_name *	dn
	)

Store the certificate DN in printable form into buf; no more than size characters will be written.

Parameters

buf	Buffer to write to
size	Maximum size of buffer
dn	The X509 name to represent

Returns

The amount of data written to the buffer, or -1 in case of an error.

int x509parse_key	(	rsa_context *	rsa,
		const unsigned char *	key,
		int	keylen,
		const unsigned char *	pwd,
		int	pwdlen
	)

Parse a private RSA key.

Parameters

rsa	RSA context to be initialized
key	input buffer
keylen	size of the buffer
pwd	password for decryption (optional)
pwdlen	size of the password

Returns

0 if successful, or a specific X509 error code

int x509parse_keyfile	(	rsa_context *	rsa,
		const char *	path,
		const char *	password
	)

Load and parse a private RSA key.

Parameters

rsa	RSA context to be initialized
path	filename to read the private key from
pwd	password to decrypt the file (can be NULL)

Returns

0 if successful, or a specific X509 error code

int x509parse_time_expired

(

const x509_time *

time

)

Check a given x509_time against the system time and check if it is valid.

Parameters

time	x509_time to check

Returns

Return 0 if the x509_time is still valid, or 1 otherwise.

int x509parse_verify	(	x509_cert *	crt,
		x509_cert *	trust_ca,
		x509_crl *	ca_crl,
		const char *	cn,
		int *	flags
	)

Verify the certificate signature.

Parameters

crt	a certificate to be verified
trust_ca	the trusted CA chain
ca_crl	the CRL chain for trusted CA's
cn	expected Common Name (can be set to NULL if the CN must not be verified)
flags	result of the verification

Returns

0 if successful or POLARSSL_ERR_X509_SIG_VERIFY_FAILED, in which case *flags will have one or more of the following values set: BADCERT_EXPIRED – BADCERT_REVOKED – BADCERT_CN_MISMATCH – BADCERT_NOT_TRUSTED

Note

TODO: add two arguments, depth and crl