X509_LOOKUP *X509_LOOKUP_new(method)
X509_LOOKUP_METHOD *method;
void X509_LOOKUP_free(ctx)
X509_LOOKUP *ctx;
int X509_LOOKUP_init(ctx)
X509_LOOKUP *ctx;
int X509_LOOKUP_by_subject(ctx, type, name, ret)
X509_LOOKUP *ctx;
int type;
X509_NAME *name;
X509_OBJECT *ret;
int X509_LOOKUP_by_issuer_serial(ctx, type, name, serial, ret)
X509_LOOKUP *ctx;
int type;
X509_NAME *name;
ASN1_INTEGER *serial;
X509_OBJECT *ret;
int X509_LOOKUP_by_fingerprint(ctx, type, bytes, len, ret)
X509_LOOKUP *ctx;
int type;
unsigned char *bytes;
int len;
X509_OBJECT *ret;
int X509_LOOKUP_by_alias(ctx, type, str, len, ret)
X509_LOOKUP *ctx;
int type;
char *str;
int len;
X509_OBJECT *ret;
int X509_LOOKUP_shutdown(ctx)
X509_LOOKUP *ctx);
int X509_LOOKUP_ctrl(ctx, cmd, argc, argl, ret)
X509_LOOKUP *ctx;
int cmd;
char *argc;
long argl;
char **ret;
X509_LOOKUP_METHOD *X509_LOOKUP_file();
X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir();
These fuctions all operate on one or both of the following structures:
typedef struct x509_lookup_st
{
int init; /* have we been started */
int skip; /* don't use us. */
X509_LOOKUP_METHOD *method; /* the functions */
char *method_data; /* method data */
X509_STORE *store_ctx; /* who owns us */
} X509_LOOKUP;
an X509_LOOKUP_METHOD,
typedef struct x509_lookup_method_st
{
char *name;
int (*new_item)();
void (*free)();
int (*init)(/* meth, char ** */);
int (*shutdown)( /* meth, char ** */);
int (*ctrl)( /* meth, char **, int cmd, char *argp, int argi */);
int (*get_by_subject)(/* meth, char **, XNAME *, X509 **ret */);
int (*get_by_issuer_serial)();
int (*get_by_fingerprint)();
int (*get_by_alias)();
} X509_LOOKUP_METHOD;
First, an application should define any X509_LOOKUP_METHODs it needs. These are means to get a certificate from disk into an internal list (X509_STORE_CTX). Two such methods are provided by the library.
by_dir.c defines:
X509_LOOKUP_METHOD x509_dir_lookup=
{
"Load certs from files in a directory",
new_dir, /* new */
free_dir, /* free */
NULL, /* init */
NULL, /* shutdown */
dir_ctrl, /* ctrl */
get_cert_by_subject, /* get_by_subject */
NULL, /* get_by_issuer_serial */
NULL, /* get_by_fingerprint */
NULL, /* get_by_alias */
};
All of the routines it references are internal functions which should not
be directly called by an application. Briefly, new_dir allocates a
new BY_DIR structure (used by this method for internal bookkeeping);
free_dir frees such a structure; dir_ctrl processes one of the
following commands:
X509_L_ADD_DIR
(a pretty short list :-) ) allowing someone to add a directory to the list of drectories that are searched; get_cert_by_subject is used to look for a certificate in the directories in the list, by subject name, where the subject name has been hashed first and we keep only the first four bytes, translated to ascii; we expect the file containing the cert (or crl) to have a name that starts with that hash.
The other lookup method provided by this library is defined in by_file.c:
X509_LOOKUP_METHOD x509_file_lookup=
{
"Load file into cache",
NULL, /* new */
NULL, /* free */
NULL, /* init */
NULL, /* shutdown */
by_file_ctrl, /* ctrl */
NULL, /* get_by_subject */
NULL, /* get_by_issuer_serial */
NULL, /* get_by_fingerprint */
NULL, /* get_by_alias */
};
No new or free function is defined; the only thing it provides is by_file_ctrl, which allows the command X509_L_FILE_LOAD, and is used to load a certificate (or crl) using X509_get_default_cert_file() or X509_get_default_cert_file_env() to get the filename it is supposed to open.
If you want to construct your own LOOKUP_METHODs then you should be reading the rest of this document; otherwise you probably want to look at the documentation on X509_STORE to see how to load these lookup methods into your X509_STORE structure for future use.
X509_LOOKUP_new creates a new X509_LOOKUP structure using the X509_LOOKUP_METHOD method passed to it as the method subfield of the structure; it returns a pointer to the new structure or NULL on error.
X509_LOOKUP_free frees the X509_LOOKUP structure passed to it, using in part the method subfield to free various parts of the structure.
X509_LOOKUP_init calls method->init on ctx if the function is not NULL. This would be called after X509_LOOKUP_new and before any real processing occurs.
X509_LOOKUP_by_subject calls ctx->method->get_by_subject with the same arguments, if the function is not NULL. This would be called to retrieve a certificate or crl from someplace given the subject name from the certificate in X509_NAME form (name). type is one of X509_LU_X509 or X509_LU_CRL and indicates whether you want a certificate or a CRL. I see that X509_LU_PKEY is also a defined type but I dunno if the code is available for looking up keys. The data and type of data (cert or crl) is returned in ret. If you want to get at the certificate (assuming it is one) you can access ret->data.x509 which is an X509 structure.
X509_LOOKUP_by_issuer_serial calls ctx->method->get_by_issuer_serial with the same arguments, if the function is not NULL. This would be called to retrieve a certificate or crl from someplace given the issuer name from the certificate in X509_NAME form (name) and the serial number as an ASN1_INTEGER (serial). type is one of X509_LU_X509 or X509_LU_CRL and indicates whether you want a certificate or a CRL. I see that X509_LU_PKEY is also a defined type but I dunno if the code is available for looking up keys. The data and type of data (cert or crl) is returned in ret. If you want to get at the certificate (assuming it is one) you can access ret->data.x509 which is an X509 structure.
X509_LOOKUP_by_fingerprint would pass len bytes of the MD5 or possibly other hash in bytes along with the type of the object to be retrieved, to ctx->method->get_by_fingerprint if it was set; this would only happen though if you write a method that has it. This library provides no methods that use such a function.
X509_LOOKUP_by_alias would pass len bytes of the alias str along with the type of the object to be retrieved, to ctx->method->get_by_alias if it was set; this would only happen though if you write a method that has it. This library provides no methods that use such a function.
X509_LOOKUP_shutdown calls ctx->method->shutdown on ctx; this should be called after all lookups using this method are completed.
X509_LOOKUP_ctrl executes ctx->method->ctrl. This is a catch-all that takes a command (one of X509_L_FILE_LOAD or X509_L_ADD_DIR at present, since nothing else has been defined). Any return value should get shoved into *ret.
X509_LOOKUP_load_file is a macro:
#define X509_LOOKUP_load_file(x,name,type) X509_LOOKUP_ctrl((x),X509_L_FILE_LOAD,(name),(long)(type),NULL)
It executes ctx->method->ctrl with X509_L_FILE_LOAD as the command. Ordinarily this should cause the certificate or crl in the file name to be read in and added to ctx->store_ctx.
X509_LOOKUP_add_dir is a macro:
#define X509_LOOKUP_add_dir(x,name,type) X509_LOOKUP_ctrl((x),X509_L_ADD_DIR,(name),(long)(type),NULL)
It executes ctx->method->ctrl with X509_L_ADD_DIR as the command. Ordinarily this should cause the directory name to be added to the list of directories that will be searched for certificates (assuming this makes sense for the particular lookup method).
X509_LOOKUP_file returns a pointer to the static method x509_file_lookup described earlier. This function is useful to call when you want to add a method to a stack of methods you are using; see X509_STORE documentation for more on this.
X509_LOOKUP_hash_dir returns a pointer to the static method x509_dir_lookup described earlier. This function is useful to call when you want to add a method to a stack of methods you are using; see X509_STORE documentation for more on this.