# x509.h File Reference

## Detailed Description

Copyright (C) 2006-2009, Paul Bakker <polarssl_maintainer at polarssl.org> All rights reserved.

Joined copyright on original XySSL code with: Christophe Devine

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.

Definition in file x509.h.

`#include "polarssl/rsa.h"`

Go to the source code of this file.

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

## Define Documentation

#define ASN1_BIT_STRING 0x03

Definition at line 84 of file x509.h.

#define ASN1_BMP_STRING 0x1E

Definition at line 96 of file x509.h.

#define ASN1_BOOLEAN 0x01

Definition at line 82 of file x509.h.

#define ASN1_CONSTRUCTED 0x20

Definition at line 98 of file x509.h.

#define ASN1_CONTEXT_SPECIFIC 0x80

Definition at line 99 of file x509.h.

#define ASN1_IA5_STRING 0x16

Definition at line 93 of file x509.h.

#define ASN1_INTEGER 0x02

Definition at line 83 of file x509.h.

#define ASN1_NULL 0x05

Definition at line 86 of file x509.h.

#define ASN1_OCTET_STRING 0x04

Definition at line 85 of file x509.h.

#define ASN1_OID 0x06

Definition at line 87 of file x509.h.

#define ASN1_PRIMITIVE 0x00

Definition at line 97 of file x509.h.

#define ASN1_PRINTABLE_STRING 0x13

Definition at line 91 of file x509.h.

#define ASN1_SEQUENCE 0x10

Definition at line 89 of file x509.h.

#define ASN1_SET 0x11

Definition at line 90 of file x509.h.

#define ASN1_T61_STRING 0x14

Definition at line 92 of file x509.h.

#define ASN1_UNIVERSAL_STRING 0x1C

Definition at line 95 of file x509.h.

#define ASN1_UTC_TIME 0x17

Definition at line 94 of file x509.h.

#define ASN1_UTF8_STRING 0x0C

Definition at line 88 of file x509.h.

#define BADCERT_CN_MISMATCH 4

Definition at line 74 of file x509.h.

#define BADCERT_EXPIRED 1

Definition at line 72 of file x509.h.

#define BADCERT_NOT_TRUSTED 8

Definition at line 75 of file x509.h.

#define BADCERT_REVOKED 2

Definition at line 73 of file x509.h.

#define BADCRL_EXPIRED 32

Definition at line 77 of file x509.h.

#define BADCRL_NOT_TRUSTED 16

Definition at line 76 of file x509.h.

#define OID_CN "\x55\x04\x03"

Definition at line 119 of file x509.h.

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

Definition at line 120 of file x509.h.

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

Definition at line 121 of file x509.h.

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

Definition at line 122 of file x509.h.

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

Definition at line 123 of file x509.h.

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

Definition at line 124 of file x509.h.

#define OID_X520 "\x55\x04"

Definition at line 118 of file x509.h.

#define PEM_LINE_LENGTH 72

Definition at line 114 of file x509.h.

#define PKCS9_EMAIL 1

Definition at line 110 of file x509.h.

#define POLARSSL_ERR_ASN1_INVALID_DATA 0x001C

Definition at line 38 of file x509.h.

#define POLARSSL_ERR_ASN1_INVALID_LENGTH 0x0018

Definition at line 36 of file x509.h.

#define POLARSSL_ERR_ASN1_LENGTH_MISMATCH 0x001A

Definition at line 37 of file x509.h.

#define POLARSSL_ERR_ASN1_OUT_OF_DATA 0x0014

Definition at line 34 of file x509.h.

#define POLARSSL_ERR_ASN1_UNEXPECTED_TAG 0x0016

Definition at line 35 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_ALG -0x00C0

Definition at line 48 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_DATE -0x0100

Definition at line 50 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_EXTENSIONS -0x0160

Definition at line 53 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_FORMAT -0x0060

Definition at line 45 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_NAME -0x00E0

Definition at line 49 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_PEM -0x0040

Definition at line 44 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_PUBKEY -0x0120

Definition at line 51 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_SERIAL -0x00A0

Definition at line 47 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_SIGNATURE -0x0140

Definition at line 52 of file x509.h.

#define POLARSSL_ERR_X509_CERT_INVALID_VERSION -0x0080

Definition at line 46 of file x509.h.

#define POLARSSL_ERR_X509_CERT_SIG_MISMATCH -0x01E0

Definition at line 57 of file x509.h.

#define POLARSSL_ERR_X509_CERT_UNKNOWN_PK_ALG -0x01C0

Definition at line 56 of file x509.h.

#define POLARSSL_ERR_X509_CERT_UNKNOWN_SIG_ALG -0x01A0

Definition at line 55 of file x509.h.

#define POLARSSL_ERR_X509_CERT_UNKNOWN_VERSION -0x0180

Definition at line 54 of file x509.h.

#define POLARSSL_ERR_X509_CERT_VERIFY_FAILED -0x0200

Definition at line 58 of file x509.h.

#define POLARSSL_ERR_X509_FEATURE_UNAVAILABLE -0x0020

Definition at line 43 of file x509.h.

#define POLARSSL_ERR_X509_KEY_INVALID_ENC_IV -0x0280

Definition at line 62 of file x509.h.

#define POLARSSL_ERR_X509_KEY_INVALID_FORMAT -0x0260

Definition at line 61 of file x509.h.

#define POLARSSL_ERR_X509_KEY_INVALID_PEM -0x0220

Definition at line 59 of file x509.h.

#define POLARSSL_ERR_X509_KEY_INVALID_VERSION -0x0240

Definition at line 60 of file x509.h.

#define POLARSSL_ERR_X509_KEY_PASSWORD_MISMATCH -0x02E0

Definition at line 65 of file x509.h.

#define POLARSSL_ERR_X509_KEY_PASSWORD_REQUIRED -0x02C0

Definition at line 64 of file x509.h.

#define POLARSSL_ERR_X509_KEY_UNKNOWN_ENC_ALG -0x02A0

Definition at line 63 of file x509.h.

#define POLARSSL_ERR_X509_POINT_ERROR -0x0300

Definition at line 66 of file x509.h.

#define POLARSSL_ERR_X509_VALUE_TO_LENGTH -0x0320

Definition at line 67 of file x509.h.

#define X509_ISSUER 0x01

Definition at line 115 of file x509.h.

#define X509_OUTPUT_DER 0x01

Definition at line 112 of file x509.h.

#define X509_OUTPUT_PEM 0x02

Definition at line 113 of file x509.h.

#define X509_SUBJECT 0x02

Definition at line 116 of file x509.h.

#define X520_COMMON_NAME 3

Definition at line 104 of file x509.h.

#define X520_COUNTRY 6

Definition at line 105 of file x509.h.

#define X520_LOCALITY 7

Definition at line 106 of file x509.h.

#define X520_ORG_UNIT 11

Definition at line 109 of file x509.h.

#define X520_ORGANIZATION 10

Definition at line 108 of file x509.h.

#define X520_STATE 8

Definition at line 107 of file x509.h.

## Typedef Documentation

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

## Function Documentation

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

int x509parse_cert_info | ( | char * | buf,
|  | size_t | size,
|  | char * | prefix,
|  | 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,
|  | 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,
|  | char * | prefix,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | 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,
|  | unsigned char * | buf,
|  | int | buflen,
|  | unsigned char * | pwd,
|  | int | pwdlen |
| ) |  |  |

Parse a private RSA key.

Parameters:

  | rsa | RSA context to be initialized
  | buf | input buffer
  | buflen | 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,
|  | char * | path,
|  | 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 | ( | 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,
|  | 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