Add semi-transparent mask to CALayer?

What you're doing wrong is using a layer mask in the first place. You are trying to shade or darken an area of your image. That's not what a layer mask does at all! Basically a layer mask punches through in an existing layer, causing whatever is behind it to show through. That's exactly what you discovered:

it's completely removing it instead

Yes, because that's what layer masks do! If you don't want that, why are you using a layer mask?

What you want is just to lay a second image view (or just a sublayer) over the first one. It contains an image that you draw. It is transparent except where it has a semi-transparent dark color fill. That will darken what's behind it. You use a clipping path to define the area that doesn't get the dark color fill.

Alternatively, alter the image in your image view by drawing on top of it with compositing or possibly using a CIFilter.