1 /* -*- mode:C; c-file-style: "bsd" -*- */ 2 /* 3 * Copyright (c) 2008-2015 Yubico AB 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are 8 * met: 9 * 10 * * Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 13 * * Redistributions in binary form must reproduce the above 14 * copyright notice, this list of conditions and the following 15 * disclaimer in the documentation and/or other materials provided 16 * with the distribution. 17 * 18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 */ 30 31 #ifndef __YKCORE_H_INCLUDED__ 32 #define __YKCORE_H_INCLUDED__ 33 34 #include <stdlib.h> 35 #include <stdbool.h> 36 #include <stdint.h> 37 38 # ifdef __cplusplus 39 extern "C" { 40 # endif 41 42 /************************************************************************* 43 ** 44 ** N O T E : For all functions that return a value, 0 and NULL indicates 45 ** an error, other values indicate success. 46 ** 47 ************************************************************************/ 48 49 /************************************************************************* 50 * 51 * Structures used. They are further defined in ykdef.h 52 * 53 ****/ 54 55 typedef struct yk_key_st YK_KEY; /* Really a USB device handle. */ 56 typedef struct yk_status_st YK_STATUS; /* Status structure, 57 filled by yk_get_status(). */ 58 59 typedef struct yk_ticket_st YK_TICKET; /* Ticket structure... */ 60 typedef struct yk_config_st YK_CONFIG; /* Configuration structure. 61 Other libraries provide access. */ 62 typedef struct yk_nav_st YK_NAV; /* Navigation structure. 63 Other libraries provide access. */ 64 typedef struct yk_frame_st YK_FRAME; /* Data frame for write operation */ 65 typedef struct ndef_st YK_NDEF; 66 typedef struct yk_device_config_st YK_DEVICE_CONFIG; 67 68 /************************************************************************* 69 * 70 * Library initialisation functions. 71 * 72 ****/ 73 extern int yk_init(void); 74 extern int yk_release(void); 75 76 /************************************************************************* 77 * 78 * Functions to get and release the key itself. 79 * 80 ****/ 81 /* opens first key available. For backwards compatability */ 82 extern YK_KEY *yk_open_first_key(void); 83 extern YK_KEY *yk_open_key(int); /* opens nth key available */ 84 extern int yk_close_key(YK_KEY *k); /* closes a previously opened key */ 85 86 /************************************************************************* 87 * 88 * Functions to get data from the key. 89 * 90 ****/ 91 /* fetches key status into the structure given by `status' */ 92 extern int yk_get_status(YK_KEY *k, YK_STATUS *status /*, int forceUpdate */); 93 /* checks that the firmware revision of the key is supported */ 94 extern int yk_check_firmware_version(YK_KEY *k); 95 extern int yk_check_firmware_version2(YK_STATUS *status); 96 /* Read the factory set serial number from a YubiKey 2.0 or higher. */ 97 extern int yk_get_serial(YK_KEY *yk, uint8_t slot, unsigned int flags, unsigned int *serial); 98 /* Wait for the key to either set or clear bits in it's status byte */ 99 extern int yk_wait_for_key_status(YK_KEY *yk, uint8_t slot, unsigned int flags, 100 unsigned int max_time_ms, 101 bool logic_and, unsigned char mask, 102 unsigned char *last_data); 103 /* Read the response to a command from the YubiKey */ 104 extern int yk_read_response_from_key(YK_KEY *yk, uint8_t slot, unsigned int flags, 105 void *buf, unsigned int bufsize, unsigned int expect_bytes, 106 unsigned int *bytes_read); 107 108 /************************************************************************* 109 * 110 * Functions to write data to the key. 111 * 112 ****/ 113 114 /* writes the given configuration to the key. If the configuration is NULL, 115 zap the key configuration. 116 acc_code has to be provided of the key has a protecting access code. */ 117 extern int yk_write_command(YK_KEY *k, YK_CONFIG *cfg, uint8_t command, 118 unsigned char *acc_code); 119 /* wrapper function of yk_write_command */ 120 extern int yk_write_config(YK_KEY *k, YK_CONFIG *cfg, int confnum, 121 unsigned char *acc_code); 122 /* writes the given ndef to the key as SLOT_NDEF */ 123 extern int yk_write_ndef(YK_KEY *yk, YK_NDEF *ndef); 124 /* writes the given ndef to the key. */ 125 extern int yk_write_ndef2(YK_KEY *yk, YK_NDEF *ndef, int confnum); 126 /* writes a device config block to the key. */ 127 extern int yk_write_device_config(YK_KEY *yk, YK_DEVICE_CONFIG *device_config); 128 /* writes a scanmap to the key. */ 129 extern int yk_write_scan_map(YK_KEY *yk, unsigned char *scan_map); 130 /* Write something to the YubiKey (a command that is). */ 131 extern int yk_write_to_key(YK_KEY *yk, uint8_t slot, const void *buf, int bufcount); 132 /* Do a challenge-response round with the key. */ 133 extern int yk_challenge_response(YK_KEY *yk, uint8_t yk_cmd, int may_block, 134 unsigned int challenge_len, const unsigned char *challenge, 135 unsigned int response_len, unsigned char *response); 136 137 extern int yk_force_key_update(YK_KEY *yk); 138 /* Get the VID and PID of an opened device. */ 139 extern int yk_get_key_vid_pid(YK_KEY *yk, int *vid, int *pid); 140 /* Get the YK4 capabilities */ 141 int yk_get_capabilities(YK_KEY *yk, uint8_t slot, unsigned int flags, 142 unsigned char *capabilities, unsigned int *len); 143 /* Set the device info (TLV string) */ 144 int yk_write_device_info(YK_KEY *yk, unsigned char *buf, unsigned int len); 145 146 147 /************************************************************************* 148 * 149 * Error handling fuctions 150 * 151 ****/ 152 extern int * _yk_errno_location(void); 153 #define yk_errno (*_yk_errno_location()) 154 const char *yk_strerror(int errnum); 155 /* The following function is only useful if yk_errno == YK_EUSBERR and 156 no other USB-related operations have been performed since the time of 157 error. */ 158 const char *yk_usb_strerror(void); 159 160 161 /* Swaps the two bytes between little and big endian on big endian machines */ 162 extern uint16_t yk_endian_swap_16(uint16_t x); 163 164 #define YK_EUSBERR 0x01 /* USB error reporting should be used */ 165 #define YK_EWRONGSIZ 0x02 166 #define YK_EWRITEERR 0x03 167 #define YK_ETIMEOUT 0x04 168 #define YK_ENOKEY 0x05 169 #define YK_EFIRMWARE 0x06 170 #define YK_ENOMEM 0x07 171 #define YK_ENOSTATUS 0x08 172 #define YK_ENOTYETIMPL 0x09 173 #define YK_ECHECKSUM 0x0a /* checksum validation failed */ 174 #define YK_EWOULDBLOCK 0x0b /* operation would block */ 175 #define YK_EINVALIDCMD 0x0c /* supplied command is invalid for this operation */ 176 #define YK_EMORETHANONE 0x0d /* expected to find only one key but found more */ 177 #define YK_ENODATA 0x0e /* no data was returned from a read */ 178 179 /* Flags for response reading. Use high numbers to not exclude the possibility 180 * to combine these with for example SLOT commands from ykdef.h in the future. 181 */ 182 #define YK_FLAG_MAYBLOCK 0x01 << 16 183 184 #define YK_CRC_OK_RESIDUAL 0xf0b8 185 186 # ifdef __cplusplus 187 } 188 # endif 189 190 #endif /* __YKCORE_H_INCLUDED__ */ 191