Skip to content

Latest commit

 

History

History
106 lines (82 loc) · 5.64 KB

conditional_compile_options.md

File metadata and controls

106 lines (82 loc) · 5.64 KB
Raw

conditional_compile_options

All conditional_compile_options are located in the build.rs files,
acos5_external/opensc-sys/build.rs
acos5_external/acos5/build.rs
acos5_external/acos5_pkcs15/build.rs (file is identical with acos5_external/acos5/build.rs)

in lines that start with
println!("cargo:rustc-cfg=

At some places I refer to conditional_compile_options as compiler switch --cfg, which names the same subject.

acos5_external/opensc-sys/build.rs

In principle, the opensc_sys binding is a general one, suitable for any purpose, generated by bindgen once for OpenSC version 0.17.0 header files and since then manually updated. The #define are the same as debian packaging does for the x86_64 target, i.e. important ones are:

/* Have OpenSSL libraries and header files */
#define ENABLE_OPENSSL 1

/* Enable secure messaging support */
#define ENABLE_SM 1

If You compile the opensc sources with different #define or #undef, then You MUST adapt the binding accordingly before using it. It's fine to use this binding with opensc built from source by:

tar xfvz opensc-*.tar.gz
cd opensc-*
./bootstrap
./configure --prefix=/usr --sysconfdir=/etc/opensc --libdir=/usr/lib/x86_64-linux-gnu
make -j4
sudo checkinstall

libdir may be different for some Posix OS and checkinstall instead of make install is just my preference (Kubuntu). Hence all conditional_compile_options originating from C headers are implicitly covered, but some new introduced:

v0_20_0 v0_21_0 v0_22_0 v0_23_0 v0_24_0 v0_25_0 v0_25_1 v0_26_0

impl_default
impl_display
acos5_impl_default
impl_newAT_newCCT_newCT

The last 4 are additions that are specific for "my purpose, the acos5 driver".

Only exactly one mandatory of the version related "compiler switches" v0_2... is active and all of the remaining, nothing should be changed here for acos5.

An option is active when it's not in a comment. Comments are lines that start with // or lines enclosed by a starting /* and a closing */

The build.rs files get processed before any other source code, and depending on the cfg= content, some source code lines may be compiled into the driver or be excluded from the driver. Rust allows to use the conditional_compile_option with operators not (negation), any ((inclusive) disjunction, also known as alternation) and all (conjunction).
E.g. the cfg= version information has i.a. direct influence on the functions sc_driver_version.

In acos5/build.rs, there is currently only one other setting active:
println!("cargo:rustc-cfg=log");

This will print debug information to the opensc-debug.log file, as specified in opensc.conf, and only if debug > 0
If You don't have logging enabled via opensc.conf or never want to look into the generated opensc-debug.log file, then it's superfluous to have logging-related source code lines and processing for the waste bin: Then just make above mentioned line a comment: //println!("cargo:rustc-cfg=log");

There is another conditional_compile option that may be interesting for users, not active by default: //println!("cargo:rustc-cfg=iup_user_consent");

Its intent is to force the driver to popup a dialog window prior to any usage of a private RSA key for enhanced security. Answer with "NO" in order to decline the RSA key usage; YES or closing the window via it's system menu [X] means accepting RSA key usage. If not declined, the driver will use the private RSA key as requested, either for sign, decipher or unwrap.

For this to work, several steps must be completed:

  1. Activate the line: println!("cargo:rustc-cfg=iup_user_consent");
  2. The 2 following lines also must be "activated": They state, what is the name of the library file to additionally link in and where to find that file. Also, of course, it requires to have IUP installed. Get precompiled binaries from http://sourceforge.net/projects/iup/files/ (latest version) and (with Linux) run the script ./install. The homepage of IUP is https://webserver2.tecgraf.puc-rio.br/iup/
  3. Even with the above completed, there is another stopping point in opensc.conf: change to user_consent_enabled = yes; to enable that feature.

Another option is centered around the question: When an operation get's executed in Secure Messaging mode, do You want to be sure to be connected with a specific hardware smart card/usb crypto token? If yes, then edit opensc.conf and fill in the hardware's serial number into ifd_serial, 8 bytes, hexadecimal notation, each byte separated by a colon. For ACOS5 V2.00 with a 6 byte serial number, add 2 zero bytes and activate line: //println!("cargo:rustc-cfg=ifd_serial_constrained_for_sm"); Obviously this makes sense only, if You have no more than 1 ACOS5 token with SM enabled.

//println!("cargo:rustc-cfg=key_gen_verbose"); // enable to print to console some info while generating RSA/ECC key pair (see function acos5_pkcs15/src/lib.rs: acos5_pkcs15_create_key) //println!("cargo:rustc-cfg=finish_verbose"); // enable to print to console some info short before finishing driver process (see function acos5_finish)

The last option //println!("cargo:rustc-cfg=dev_relax_signature_constraints_for_raw"); came up when using pkcs11-tool --test -login and when the function acos5_init did set
rsa_algo_flags |= SC_ALGORITHM_RSA_RAW; I don't know the current state, but at the time of testing that, the input from pkcs11-tool to sign with SC_ALGORITHM_RSA_RAW didn't comply with PKCS#1, and only using this option did avoid errors with pkcs11-tool. So this needs to be checked once again, also in conjunction with meanwhile available PSS padding. Don't use that currently !

//println!("cargo:rustc-cfg=enforce_restricted_op_mode_byte"); //println!("cargo:rustc-cfg=enforce_restricted_op_mode_byte_no_fips");