1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright 2002, 2003 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 27 #ifndef _P12AUX_H 28 #define _P12AUX_H 29 30 #pragma ident "%Z%%M% %I% %E% SMI" 31 32 #include <openssl/pkcs12.h> 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /* 39 * I really hate to do this. It's pretty gross, but go ahead and use the 40 * macros and functions already defined to provide new EVP_PKEY-specific 41 * macros, for use within this file only. 42 * 43 * My apologies. 44 */ 45 DECLARE_STACK_OF(EVP_PKEY) 46 47 #define sk_EVP_PKEY_new_null() SKM_sk_new_null(EVP_PKEY) 48 #define sk_EVP_PKEY_free(st) SKM_sk_free(EVP_PKEY, (st)) 49 #define sk_EVP_PKEY_num(st) SKM_sk_num(EVP_PKEY, (st)) 50 #define sk_EVP_PKEY_value(st, i) SKM_sk_value(EVP_PKEY, (st), (i)) 51 #define sk_EVP_PKEY_push(st, val) SKM_sk_push(EVP_PKEY, (st), (val)) 52 #define sk_EVP_PKEY_find(st, val) SKM_sk_find(EVP_PKEY, (st), (val)) 53 #define sk_EVP_PKEY_delete(st, i) SKM_sk_delete(EVP_PKEY, (st), (i)) 54 #define sk_EVP_PKEY_delete_ptr(st, ptr) SKM_sk_delete_ptr(EVP_PKEY, (st), (ptr)) 55 #define sk_EVP_PKEY_insert(st, val, i) SKM_sk_insert(EVP_PKEY, (st), (val), (i)) 56 #define sk_EVP_PKEY_pop_free(st, free_func) SKM_sk_pop_free(EVP_PKEY, (st), \ 57 (free_func)) 58 #define sk_EVP_PKEY_pop(st) SKM_sk_pop(EVP_PKEY, (st)) 59 60 /* 61 * This type indicates what to do with an attribute being returned. 62 */ 63 typedef enum { 64 GETDO_COPY = 1, /* Simply return the value of the attribute */ 65 GETDO_DEL /* Delete the attribute at the same time. */ 66 } getdo_actions_t; 67 68 /* 69 * The following is used to call the sunw_print_times function which is 70 * described at the bottom of the page. 71 */ 72 typedef enum { 73 PRNT_NOT_BEFORE = 1, /* Print 'not before' date */ 74 PRNT_NOT_AFTER, /* Print 'not after' date */ 75 PRNT_BOTH /* Prints both dates */ 76 } prnt_actions_t; 77 78 /* 79 * For sunw_pkcs12_parse, the following are values for bits that indicate 80 * various types of searches/matching to do. Any of these values can be 81 * OR'd together. However, the order in which an attempt will be made 82 * to satisfy them is the order in which they are listed below. The 83 * exception is DO_NONE. It should not be OR'd with any other value. 84 */ 85 #define DO_NONE 0x00 /* Don't even try to match */ 86 #define DO_FIND_KEYID 0x01 /* 1st cert, key with matching localkeyid */ 87 #define DO_FIND_FN 0x02 /* 1st cert, key with matching friendlyname */ 88 #define DO_FIRST_PAIR 0x04 /* Return first matching cert/key pair found */ 89 #define DO_LAST_PAIR 0x08 /* Return last matching cert/key pair found */ 90 #define DO_UNMATCHING 0x10 /* Return first cert and/or key */ 91 92 /* Bits returned, which indicate what values were found. */ 93 #define FOUND_PKEY 0x01 /* Found one or more private key */ 94 #define FOUND_CERT 0x02 /* Found one or more client certificate */ 95 #define FOUND_CA_CERTS 0x04 /* Added at least one cert to the CA list */ 96 #define FOUND_XPKEY 0x08 /* Found at least one private key which does */ 97 /* not match a certificate in the certs list */ 98 99 /* 100 * sunw_cryto_init() does crypto-specific initialization. 101 * 102 * Arguments: 103 * None. 104 * 105 * Returns: 106 * None. 107 */ 108 void sunw_crypto_init(void); 109 110 /* 111 * sunw_PKCS12_parse() parses a pkcs#12 structure and returns component parts. 112 * 113 * Parse and decrypt a PKCS#12 structure returning user key, user cert and/or 114 * other (CA) certs. Note either ca should be NULL, *ca should be NULL, 115 * or it should point to a valid STACK_OF(X509) structure. pkey and cert can 116 * be passed uninitialized. 117 * 118 * Arguments: 119 * p12 - Structure with pkcs12 info to be parsed 120 * pass - Pass phrase for the private key and entire pkcs12 wad (possibly 121 * empty) or NULL if there is none. 122 * matchty - Info about which certs/keys to return if many are in the file. 123 * keyid_str- If private key localkeyids are to match a predetermined value, 124 * the value to match. 125 * keyid_len- Length of the keyid byte string. 126 * name_str - If friendlynames are to match a predetermined value, the value 127 * to match. 128 * pkey - Points to location pointing to the private key returned. 129 * cert - Points to locaiton which points to the client cert returned 130 * ca - Points to location that points to a stack of 'certificate 131 * authority' certs (possibly including trust anchors). 132 * 133 * Match based on the value of 'matchty' and the contents of 'keyid_str' 134 * and/or 'name_str', as appropriate. Go through the lists of certs and 135 * private keys which were taken from the pkcs12 structure, looking for 136 * matches of the requested type. This function only searches the lists of 137 * matching private keys and client certificates. Kinds of matches allowed, 138 * and the order in which they will be checked, are: 139 * 140 * 1) Find the key and/or cert whose localkeyid attributes matches 'cmpstr' 141 * 2) Find the key and/or cert whose friendlyname attributes matches 'cmpstr' 142 * 3) Return the first matching key/cert pair found. 143 * 4) Return the last matching key/cert pair found. 144 * 5) Return whatever cert and/or key are available, even unmatching. 145 * 146 * Append the certs which do not have matching private keys and which were 147 * not selected to the CA list. 148 * 149 * If none of the bits are set, no client certs or private keys will be 150 * returned. CA (aka trust anchor) certs can be. 151 * 152 * Notes: If #3 is selected, then #4 will never occur. CA certs will be 153 * selected after a cert/key pairs are isolated. 154 * 155 * Returns: 156 * < 0 - An error returned. Call ERR_get_error() to get errors information. 157 * Where possible, memory has been freed. 158 * >= 0 - Objects were found and returned. Which objects are indicated by 159 * which bits are set (FOUND_PKEY, FOUND_CERT, FOUND_CA_CERTS). 160 */ 161 int sunw_PKCS12_parse(PKCS12 *, const char *, int, char *, int, char *, 162 EVP_PKEY **, X509 **, STACK_OF(X509) **); 163 164 165 /* 166 * sunw_PKCS12_create() creates a pkcs#12 structure and given component parts. 167 * 168 * Given one or more of user private key, user cert and/or other (CA) certs, 169 * return an encrypted PKCS12 structure containing them. 170 * 171 * Arguments: 172 * pass - Pass phrase for the pkcs12 structure and private key (possibly 173 * empty) or NULL if there is none. It will be used to encrypt 174 * both the private key(s) and as the pass phrase for the whole 175 * pkcs12 wad. 176 * pkey - Points to stack of private keys. 177 * cert - Points to stack of client (public ke) certs 178 * ca - Points to stack of 'certificate authority' certs (or trust 179 * anchors). 180 * 181 * Note that any of these may be NULL. 182 * 183 * Returns: 184 * NULL - An error occurred. 185 * != NULL - Address of PKCS12 structure. The user is responsible for 186 * freeing the memory when done. 187 */ 188 PKCS12 *sunw_PKCS12_create(const char *, STACK_OF(EVP_PKEY) *, STACK_OF(X509) *, 189 STACK_OF(X509) *); 190 191 192 /* 193 * sunw_split_certs() - Given a list of certs and a list of private keys, 194 * moves certs which match one of the keys to a different stack. 195 * 196 * Arguments: 197 * allkeys - Points to a stack of private keys to search. 198 * allcerts - Points to a stack of certs to be searched. 199 * keycerts - Points to address of a stack of certs with matching private 200 * keys. They are moved from 'allcerts'. This may not be NULL 201 * when called. If *keycerts is NULL upon entry, a new stack will 202 * be allocated. Otherwise, it must be a valid STACK_OF(509). 203 * nocerts - Points to address of a stack for keys which have no matching 204 * certs. Keys are moved from 'allkeys' here when they have no 205 * matching certs. If this is NULL, matchless keys will be 206 * discarded. 207 * 208 * Notes: If an error occurs while moving certs, the cert being move may be 209 * lost. 'keycerts' may only contain part of the matching certs. The number 210 * of certs successfully moved can be found by checking sk_X509_num(keycerts). 211 * 212 * If there is a key which does not have a matching cert, it is moved to 213 * the list nocerts. 214 * 215 * If all certs are removed from 'certs' and/or 'pkeys', it will be the 216 * caller's responsibility to free the empty stacks. 217 * 218 * Returns: 219 * < 0 - An error returned. Call ERR_get_error() to get errors information. 220 * Where possible, memory has been freed. 221 * >= 0 - The number of certs moved from 'cert' to 'pkcerts'. 222 */ 223 int sunw_split_certs(STACK_OF(EVP_PKEY) *, STACK_OF(X509) *, STACK_OF(X509) **, 224 STACK_OF(EVP_PKEY) **); 225 226 /* 227 * sunw_evp_pkey_free() Given an EVP_PKEY structure, free any attributes 228 * that are attached. Then free the EVP_PKEY itself. 229 * 230 * This is the replacement for EVP_PKEY_free() for the sunw stuff. 231 * It should be used in places where EVP_PKEY_free would be used, 232 * including calls to sk_EVP_PKEY_pop_free(). 233 * 234 * Arguments: 235 * pkey - Entry which potentially has attributes to be freed. 236 * 237 * Returns: 238 * None. 239 */ 240 void sunw_evp_pkey_free(EVP_PKEY *); 241 242 /* 243 * sunw_set_localkeyid() sets the localkeyid in a cert, a private key or 244 * both. Any existing localkeyid will be discarded. 245 * 246 * Arguments: 247 * keyid_str- A byte string with the localkeyid to set 248 * keyid_len- Length of the keyid byte string. 249 * pkey - Points to a private key to set the keyidstr in. 250 * cert - Points to a cert to set the keyidstr in. 251 * 252 * Note that setting a keyid into a cert which will not be written out as 253 * a PKCS12 cert is pointless since it will be lost. 254 * 255 * Returns: 256 * 0 - Success. 257 * < 0 - An error occurred. It was probably an error in allocating 258 * memory. The error will be set in the error stack. Call 259 * ERR_get_error() to get specific information. 260 */ 261 int sunw_set_localkeyid(const char *, int, EVP_PKEY *, X509 *); 262 263 264 /* 265 * sunw_get_pkey_localkeyid() gets the localkeyid from a private key. It can 266 * optionally remove the value found. 267 * 268 * Arguments: 269 * dowhat - What to do with the attributes (remove them or copy them). 270 * pkey - Points to a private key to set the keyidstr in. 271 * keyid_str- Points to a location which will receive the pointer to 272 * a byte string containing the binary localkeyid. Note that 273 * this is a copy, and the caller must free it. 274 * keyid_len- Length of keyid_str. 275 * 276 * Returns: 277 * >= 0 - The number of characters in the keyid returned. 278 * < 0 - An error occurred. It was probably an error in allocating 279 * memory. The error will be set in the error stack. Call 280 * ERR_get_error() to get specific information. 281 */ 282 int sunw_get_pkey_localkeyid(getdo_actions_t, EVP_PKEY *, char **, int *); 283 284 285 /* 286 * sunw_get_pkey_fname() gets the friendlyName from a private key. It can 287 * optionally remove the value found. 288 * 289 * Arguments: 290 * dowhat - What to do with the attributes (remove them or just return 291 * them). 292 * pkey - Points to a private key to get the keyid from 293 * fname - Points to a location which will receive the pointer to a 294 * byte string with the ASCII friendlyname 295 * 296 * Returns: 297 * >= 0 - The number of characters in the keyid returned. 298 * < 0 - An error occurred. It was probably an error in allocating 299 * memory. The error will be set in the error stack. Call 300 * ERR_get_error() to get specific information. 301 */ 302 int sunw_get_pkey_fname(getdo_actions_t, EVP_PKEY *, char **); 303 304 305 /* 306 * sunw_find_localkeyid() searches stacks of certs and private keys, and 307 * returns the first matching cert/private key found. 308 * 309 * Look for a keyid in a stack of certs. if 'certs' is NULL and 'pkeys' is 310 * not NULL, search the list of private keys. Move the matching cert to 311 * 'matching_cert' and its matching private key to 'matching_pkey'. If no 312 * cert or keys match, no match occurred. 313 * 314 * Arguments: 315 * keyid_str- A byte string with the localkeyid to match 316 * keyid_len- Length of the keyid byte string. 317 * pkeys - Points to a stack of private keys which match the certs. 318 * This may be NULL, in which case no keys are returned. 319 * certs - Points to a stack of certs to search. If NULL, search the 320 * stack of keys instead. 321 * matching_pkey 322 * - Pointer to receive address of first matching pkey found. 323 * 'matching_pkey' must not be NULL; '*matching_pkey' will be 324 * reset. 325 * matching_cert 326 * - Pointer to receive address of first matching cert found. 327 * 'matching_cert' must not be NULL; '*matching_cert' will be 328 * reset. 329 * 330 * Returns: 331 * < 0 - An error returned. Call ERR_get_error() to get errors information. 332 * Where possible, memory has been freed. 333 * >= 0 - Objects were found and returned. Which objects are indicated by 334 * which bits are set (FOUND_PKEY and/or FOUND_CERT). 335 */ 336 int sunw_find_localkeyid(char *, int, STACK_OF(EVP_PKEY) *, STACK_OF(X509) *, 337 EVP_PKEY **, X509 **); 338 339 340 /* 341 * sunw_find_fname() searches stacks of certs and private keys for one with 342 * a matching friendlyname and returns the first matching cert/private 343 * key found. 344 * 345 * Look for a friendlyname in a stack of certs. if 'certs' is NULL and 'pkeys' 346 * is not NULL, search the list of private keys. Move the matching cert to 347 * 'matching_cert' and its matching private key to 'matching_pkey'. If no 348 * cert or keys match, no match occurred. 349 * 350 * Arguments: 351 * fname - Friendlyname to find (NULL-terminated ASCII string). 352 * pkeys - Points to a stack of private keys which match the certs. 353 * This may be NULL, in which case no keys are returned. 354 * certs - Points to a stack of certs to search. If NULL, search the 355 * stack of keys instead. 356 * matching_pkey 357 * - Pointer to receive address of first matching pkey found. 358 * matching_cert 359 * - Pointer to receive address of first matching cert found. 360 * 361 * Returns: 362 * < 0 - An error returned. Call ERR_get_error() to get errors information. 363 * Where possible, memory has been freed. 364 * >= 0 - Objects were found and returned. Which objects are indicated by 365 * which bits are set (FOUND_PKEY and/or FOUND_CERT). 366 */ 367 int sunw_find_fname(char *, STACK_OF(EVP_PKEY) *, STACK_OF(X509) *, EVP_PKEY **, 368 X509 **); 369 370 371 /* 372 * sunw_print_times() formats and prints cert times to the given file. 373 * 374 * The label is printed on one line. One or both dates are printed on 375 * the following line or two, each with it's own indented label in the 376 * format: 377 * 378 * label 379 * 'not before' date: whatever 380 * 'not after' date: whatever 381 * 382 * Arguments: 383 * fp - file pointer for file to write to. 384 * dowhat - what field(s) to print. 385 * label - Label to use. If NULL, no line will be printed. 386 * cert - Points to a client or CA cert to check 387 * 388 * Returns: 389 * < 0 - An error occured. 390 * >= 0 - Number of lines written. 391 */ 392 int sunw_print_times(FILE *, prnt_actions_t, char *, X509 *); 393 394 395 /* 396 * sunw_check_keys() compares the public key in the certificate and a 397 * private key to ensure that they match. 398 * 399 * Arguments: 400 * cert - Points to a certificate. 401 * pkey - Points to a private key. 402 * 403 * Returns: 404 * == 0 - These do not match. 405 * != 0 - The cert's public key and the private key match. 406 */ 407 int sunw_check_keys(X509 *, EVP_PKEY *); 408 409 410 /* 411 * sunw_issuer_attrs - Given a cert, return the issuer-specific attributes 412 * as one ASCII string. 413 * 414 * Arguments: 415 * cert - Cert to process 416 * buf - If non-NULL, buffer to receive string. If NULL, one will 417 * be allocated and its value will be returned to the caller. 418 * len - If 'buff' is non-null, the buffer's length. 419 * 420 * This returns an ASCII string with all issuer-related attributes in one 421 * string separated by '/' characters. Each attribute begins with its name 422 * and an equal sign. Two attributes (ATTR1 and Attr2) would have the 423 * following form: 424 * 425 * ATTR1=attr_value/ATTR2=attr2_value 426 * 427 * Returns: 428 * != NULL - Pointer to the ASCII string containing the issuer-related 429 * attributes. If the 'buf' argument was NULL, this is a 430 * dynamically-allocated buffer and the caller will have the 431 * responsibility for freeing it. 432 * NULL - Memory needed to be allocated but could not be. Errors 433 * are set on the error stack. 434 */ 435 char *sunw_issuer_attrs(X509 *cert, char *buf, int len); 436 437 438 /* 439 * sunw_subject_attrs - Given a cert, return the subject-specific attributes 440 * as one ASCII string. 441 * 442 * Arguments: 443 * cert - Cert to process 444 * buf - If non-NULL, buffer to receive string. If NULL, one will 445 * be allocated and its value will be returned to the caller. 446 * len - If 'buff' is non-null, the buffer's length. 447 * 448 * This returns an ASCII string with all subject-related attributes in one 449 * string separated by '/' characters. Each attribute begins with its name 450 * and an equal sign. Two attributes (ATTR1 and Attr2) would have the 451 * following form: 452 * 453 * ATTR1=attr_value/ATTR2=attr2_value 454 * 455 * Returns: 456 * != NULL - Pointer to the ASCII string containing the subject-related 457 * attributes. If the 'buf' argument was NULL, this is a 458 * dynamically-allocated buffer and the caller will have the 459 * responsibility for freeing it. 460 * NULL - Memory needed to be allocated but could not be. Errors 461 * are set on the error stack. 462 */ 463 char *sunw_subject_attrs(X509 *cert, char *buf, int len); 464 465 /* 466 * sunw_append_keys - Given two stacks of private keys, remove the keys from 467 * the second stack and append them to the first. Both stacks must exist 468 * at time of call. 469 * 470 * Arguments: 471 * dst - the stack to receive the keys from 'src' 472 * src - the stack whose keys are to be moved. 473 * 474 * Returns: 475 * -1 - An error occurred. The error status is set. 476 * >= 0 - The number of keys that were copied. 477 */ 478 int sunw_append_keys(STACK_OF(EVP_PKEY) *, STACK_OF(EVP_PKEY) *); 479 480 481 #ifdef __cplusplus 482 } 483 #endif 484 485 #endif /* _P12AUX_H */ 486